| Message ID | 20210621175234.1079004-2-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | pull: documentation improvements | expand |
On 22/06/21 00.52, Felipe Contreras wrote: > We want users to know what is a fast-forward in order to understand the > default warning. > > Let's expand the explanation in order to cover both the simple, and the > complex cases with as much detail as possible. > > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> > --- > Documentation/git-pull.txt | 41 ++++++++++++++++++++++++++++++++------ > 1 file changed, 35 insertions(+), 6 deletions(-) > > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > index 5c3fb67c01..142df1c4a1 100644 > --- a/Documentation/git-pull.txt > +++ b/Documentation/git-pull.txt > @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > ------------ > A---B---C master on origin > / > - D---E---F---G master > + D---E master > ^ > origin/master in your repository > ------------ > > Then "`git pull`" will fetch and replay the changes from the remote > `master` branch since it diverged from the local `master` (i.e., `E`) > -until its current commit (`C`) on top of `master` and record the > -result in a new commit along with the names of the two parent commits > -and a log message from the user describing the changes. > +until its current commit (`C`) on top of `master`. > + > +After the remote changes have been synchronized, the local `master` will > +be fast-forwarded to the same commit as the remote one, therefore > +creating a linear history. > + > +------------ > + D---E---A---B---C master, origin/master > +------------ > + Isn't fast-forward merge simply moving HEAD to point at newly incoming commit from origin (in this case commit C) without creating merge commit?
Bagas Sanjaya wrote: > On 22/06/21 00.52, Felipe Contreras wrote: > > We want users to know what is a fast-forward in order to understand the > > default warning. > > > > Let's expand the explanation in order to cover both the simple, and the > > complex cases with as much detail as possible. > > > > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> > > --- > > Documentation/git-pull.txt | 41 ++++++++++++++++++++++++++++++++------ > > 1 file changed, 35 insertions(+), 6 deletions(-) > > > > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > > index 5c3fb67c01..142df1c4a1 100644 > > --- a/Documentation/git-pull.txt > > +++ b/Documentation/git-pull.txt > > @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > > ------------ > > A---B---C master on origin > > / > > - D---E---F---G master > > + D---E master > > ^ > > origin/master in your repository > > ------------ > > > > Then "`git pull`" will fetch and replay the changes from the remote > > `master` branch since it diverged from the local `master` (i.e., `E`) > > -until its current commit (`C`) on top of `master` and record the > > -result in a new commit along with the names of the two parent commits > > -and a log message from the user describing the changes. > > +until its current commit (`C`) on top of `master`. > > + > > +After the remote changes have been synchronized, the local `master` will > > +be fast-forwarded to the same commit as the remote one, therefore > > +creating a linear history. > > + > > +------------ > > + D---E---A---B---C master, origin/master > > +------------ > > + > > Isn't fast-forward merge simply moving HEAD to point at newly incoming > commit from origin (in this case commit C) without creating merge commit? Yes, but that's not always possible. The changed documentation is trying to shine a light into when it is possible, when it isn't, and why.
On 21/06/2021 18:52, Felipe Contreras wrote: > We want users to know what is a fast-forward in order to understand the > default warning. > > Let's expand the explanation in order to cover both the simple, and the > complex cases with as much detail as possible. > > Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> > --- > Documentation/git-pull.txt | 41 ++++++++++++++++++++++++++++++++------ > 1 file changed, 35 insertions(+), 6 deletions(-) > > diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt > index 5c3fb67c01..142df1c4a1 100644 > --- a/Documentation/git-pull.txt > +++ b/Documentation/git-pull.txt > @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > ------------ > A---B---C master on origin > / > - D---E---F---G master > + D---E master > ^ > origin/master in your repository > ------------ > > Then "`git pull`" will fetch and replay the changes from the remote > `master` branch since it diverged from the local `master` (i.e., `E`) > -until its current commit (`C`) on top of `master` and record the > -result in a new commit along with the names of the two parent commits > -and a log message from the user describing the changes. > +until its current commit (`C`) on top of `master`. > + > +After the remote changes have been synchronized, the local `master` will > +be fast-forwarded to the same commit as the remote one, therefore Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? I.E. we highlight the term "fast-forward" (the purpose of the patch) and we hint at the underlying mechanism of simply moving the branch pointer. > +creating a linear history. > + > +------------ > + D---E---A---B---C master, origin/master > +------------ > + > +However, a non-fast-forward case looks very different: > + > +------------ > + A---B---C origin/master > + / > + D---E---F---G master > +------------ > + > +If there are additional changes in the local `master`, it's > +not possible to fast-forward, so a decision must be made how to > +synchronize the local, and remote brances. > + > +In these situations `git pull` will warn you about your possible > +options, which are either merge (`--no-rebase`), or rebase (`--rebase`). > +However, by default it will continue doing a merge. > + > +A merge will create a new commit with two parent commits (`G` and `C`) > +and a log message describing the changes, which you can edit. > > ------------ > A---B---C origin/master > @@ -58,8 +83,11 @@ and a log message from the user describing the changes. > D---E---F---G---H master > ------------ > > +Once the merge commit is created (`H`), your local `master` branch has > +incorporated the changes of the remote `master` branch. > + > See linkgit:git-merge[1] for details, including how conflicts > -are presented and handled. > +are presented and handled, and also linkgit:git-rebase[1]. > > In Git 1.7.0 or later, to cancel a conflicting merge, use > `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' > @@ -248,7 +276,8 @@ version. > > SEE ALSO > -------- > -linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] > +linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-rebase[1], > +linkgit:git-config[1] > > GIT > ---
Philip Oakley wrote: > On 21/06/2021 18:52, Felipe Contreras wrote: > > --- a/Documentation/git-pull.txt > > +++ b/Documentation/git-pull.txt > > @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > > ------------ > > A---B---C master on origin > > / > > - D---E---F---G master > > + D---E master > > ^ > > origin/master in your repository > > ------------ > > > > Then "`git pull`" will fetch and replay the changes from the remote > > `master` branch since it diverged from the local `master` (i.e., `E`) > > -until its current commit (`C`) on top of `master` and record the > > -result in a new commit along with the names of the two parent commits > > -and a log message from the user describing the changes. > > +until its current commit (`C`) on top of `master`. > > + > > +After the remote changes have been synchronized, the local `master` will > > +be fast-forwarded to the same commit as the remote one, therefore > > Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? No, there's multiple steps: 1. origin/master is synchronizd with master on origin 2. master is fast-forwarded to origin/master So, after 1 is done, 2 will happen.
Hi Felipe, On 24/06/2021 15:31, Felipe Contreras wrote: > Philip Oakley wrote: >> On 21/06/2021 18:52, Felipe Contreras wrote: >>> --- a/Documentation/git-pull.txt >>> +++ b/Documentation/git-pull.txt >>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is >>> ------------ >>> A---B---C master on origin >>> / >>> - D---E---F---G master >>> + D---E master >>> ^ >>> origin/master in your repository >>> ------------ >>> >>> Then "`git pull`" will fetch and replay the changes from the remote >>> `master` branch since it diverged from the local `master` (i.e., `E`) >>> -until its current commit (`C`) on top of `master` and record the >>> -result in a new commit along with the names of the two parent commits >>> -and a log message from the user describing the changes. >>> +until its current commit (`C`) on top of `master`. >>> + >>> +After the remote changes have been synchronized, the local `master` will >>> +be fast-forwarded to the same commit as the remote one, therefore >> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? > No, there's multiple steps: My key point was to 'quote' the fast-forward term. And then (if suitable, with appropriate grammar corrections) indicate subtly that 'nothing actually moved', we just moved the post-it note showing the branch-name on the DAG [hence the confusion about timing] ;-) > > 1. origin/master is synchronizd with master on origin > 2. master is fast-forwarded to origin/master > > So, after 1 is done, 2 will happen. > -- Philip
Philip Oakley wrote: > Hi Felipe, > On 24/06/2021 15:31, Felipe Contreras wrote: > > Philip Oakley wrote: > >> On 21/06/2021 18:52, Felipe Contreras wrote: > >>> --- a/Documentation/git-pull.txt > >>> +++ b/Documentation/git-pull.txt > >>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > >>> ------------ > >>> A---B---C master on origin > >>> / > >>> - D---E---F---G master > >>> + D---E master > >>> ^ > >>> origin/master in your repository > >>> ------------ > >>> > >>> Then "`git pull`" will fetch and replay the changes from the remote > >>> `master` branch since it diverged from the local `master` (i.e., `E`) > >>> -until its current commit (`C`) on top of `master` and record the > >>> -result in a new commit along with the names of the two parent commits > >>> -and a log message from the user describing the changes. > >>> +until its current commit (`C`) on top of `master`. > >>> + > >>> +After the remote changes have been synchronized, the local `master` will > >>> +be fast-forwarded to the same commit as the remote one, therefore > >> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? > > No, there's multiple steps: > My key point was to 'quote' the fast-forward term. fast-forward is an English word [1], there's no need to quote it as if it weren't. > And then (if suitable, with appropriate grammar corrections) indicate > subtly that 'nothing actually moved', we just moved the post-it note > showing the branch-name on the DAG [hence the confusion about timing] ;-) A branch is a "post-it note", moving the post-it note is the same thing as moving the branch. Both the "origin/master" branch, and the "master" branch moved. So I don't know how exactly "nothing actually moved". Perhaps you meant no commit was created, and therefore the DAG didn't change. Maybe instead of saying "creating a linear history", "representing a linear history"? [1] https://www.merriam-webster.com/dictionary/fast-forward
On 24/06/2021 20:05, Felipe Contreras wrote: > Philip Oakley wrote: >> Hi Felipe, >> On 24/06/2021 15:31, Felipe Contreras wrote: >>> Philip Oakley wrote: >>>> On 21/06/2021 18:52, Felipe Contreras wrote: >>>>> --- a/Documentation/git-pull.txt >>>>> +++ b/Documentation/git-pull.txt >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is >>>>> ------------ >>>>> A---B---C master on origin >>>>> / >>>>> - D---E---F---G master >>>>> + D---E master >>>>> ^ >>>>> origin/master in your repository >>>>> ------------ >>>>> >>>>> Then "`git pull`" will fetch and replay the changes from the remote >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) >>>>> -until its current commit (`C`) on top of `master` and record the >>>>> -result in a new commit along with the names of the two parent commits >>>>> -and a log message from the user describing the changes. >>>>> +until its current commit (`C`) on top of `master`. >>>>> + >>>>> +After the remote changes have been synchronized, the local `master` will >>>>> +be fast-forwarded to the same commit as the remote one, therefore >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? >>> No, there's multiple steps: >> My key point was to 'quote' the fast-forward term. > fast-forward is an English word [1], there's no need to quote it as if > it weren't. You appear to be arguing that your "explain what is a fast-forward" (subject line of the patch) doesn't need, within the patch, to explain that it is about the term "fast-forward", being used in a Git specific way... > >> And then (if suitable, with appropriate grammar corrections) indicate >> subtly that 'nothing actually moved', we just moved the post-it note >> showing the branch-name on the DAG [hence the confusion about timing] ;-) > A branch is a "post-it note", moving the post-it note is the same thing > as moving the branch. > > Both the "origin/master" branch, and the "master" branch moved. So I > don't know how exactly "nothing actually moved". > > Perhaps you meant no commit was created, and therefore the DAG didn't > change. > > Maybe instead of saying "creating a linear history", "representing a > linear history"? > > [1] https://www.merriam-webster.com/dictionary/fast-forward > P.
Philip Oakley wrote: > On 24/06/2021 20:05, Felipe Contreras wrote: > > Philip Oakley wrote: > >> Hi Felipe, > >> On 24/06/2021 15:31, Felipe Contreras wrote: > >>> Philip Oakley wrote: > >>>> On 21/06/2021 18:52, Felipe Contreras wrote: > >>>>> --- a/Documentation/git-pull.txt > >>>>> +++ b/Documentation/git-pull.txt > >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > >>>>> ------------ > >>>>> A---B---C master on origin > >>>>> / > >>>>> - D---E---F---G master > >>>>> + D---E master > >>>>> ^ > >>>>> origin/master in your repository > >>>>> ------------ > >>>>> > >>>>> Then "`git pull`" will fetch and replay the changes from the remote > >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) > >>>>> -until its current commit (`C`) on top of `master` and record the > >>>>> -result in a new commit along with the names of the two parent commits > >>>>> -and a log message from the user describing the changes. > >>>>> +until its current commit (`C`) on top of `master`. > >>>>> + > >>>>> +After the remote changes have been synchronized, the local `master` will > >>>>> +be fast-forwarded to the same commit as the remote one, therefore > >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? > >>> No, there's multiple steps: > >> My key point was to 'quote' the fast-forward term. > > fast-forward is an English word [1], there's no need to quote it as if > > it weren't. > > You appear to be arguing that your "explain what is a fast-forward" > (subject line of the patch) doesn't need, within the patch, to explain > that it is about the term "fast-forward", being used in a Git specific > way... When you are trying to explain the meaning of a word it's generally better to not use that word in the explanation. For example if you are trying to explain "recursion", but you use "recursion" in the explanation, that kinds of defeats the purpose. So yes, in the sentence "the local `master` will be fast-forwarded to the same commit as the remote one", the verb "fast-forwarded" can easily be replaced with "advanced" and no meaning would be lost. The meaning of this "fast-forward" verb is the same as when you fast-forward a tape, and is not git-specific.
On Thu, Jun 24 2021, Felipe Contreras wrote: > Philip Oakley wrote: >> On 24/06/2021 20:05, Felipe Contreras wrote: >> > Philip Oakley wrote: >> >> Hi Felipe, >> >> On 24/06/2021 15:31, Felipe Contreras wrote: >> >>> Philip Oakley wrote: >> >>>> On 21/06/2021 18:52, Felipe Contreras wrote: >> >>>>> --- a/Documentation/git-pull.txt >> >>>>> +++ b/Documentation/git-pull.txt >> >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is >> >>>>> ------------ >> >>>>> A---B---C master on origin >> >>>>> / >> >>>>> - D---E---F---G master >> >>>>> + D---E master >> >>>>> ^ >> >>>>> origin/master in your repository >> >>>>> ------------ >> >>>>> >> >>>>> Then "`git pull`" will fetch and replay the changes from the remote >> >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) >> >>>>> -until its current commit (`C`) on top of `master` and record the >> >>>>> -result in a new commit along with the names of the two parent commits >> >>>>> -and a log message from the user describing the changes. >> >>>>> +until its current commit (`C`) on top of `master`. >> >>>>> + >> >>>>> +After the remote changes have been synchronized, the local `master` will >> >>>>> +be fast-forwarded to the same commit as the remote one, therefore >> >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? >> >>> No, there's multiple steps: >> >> My key point was to 'quote' the fast-forward term. >> > fast-forward is an English word [1], there's no need to quote it as if >> > it weren't. >> >> You appear to be arguing that your "explain what is a fast-forward" >> (subject line of the patch) doesn't need, within the patch, to explain >> that it is about the term "fast-forward", being used in a Git specific >> way... > > When you are trying to explain the meaning of a word it's generally > better to not use that word in the explanation. For example if you are > trying to explain "recursion", but you use "recursion" in the > explanation, that kinds of defeats the purpose. > > So yes, in the sentence "the local `master` will be fast-forwarded to > the same commit as the remote one", the verb "fast-forwarded" can easily > be replaced with "advanced" and no meaning would be lost. > > The meaning of this "fast-forward" verb is the same as when you > fast-forward a tape, and is not git-specific. Using quotes for a term like 'fast-forward' or some made up word like 'qibbix' doesn't just serve the purpose of clarifying which ones are in the dictionary, but also to establish that the quoted word is jargon within the context of the documentation. If I invent a new and exciting way to cut grass I might say my new machine 'shaves' the grass. The word "shave" is something I assume everyone knows, but I'm making it clear that I'm referring to the exciting mode of operation of my new death machine. So I think it Philip's suggestion makes sense. We're not talking about how to fast-forward a tape, but what happens in git when we use that term. As an aside after however many years of using git this is the first time I made the connection to that usage of the term, I thought it was jargon git invented. That's also something to consider, I've also actually seen an interacted with a tape record and VHS tape in my lifetime, but I suspect many readers of this documentation have not. This isn't something for your patch, but I wonder more generally if we shouldn't consider moving away from the term entirely, and just say a branch was one of: * advanced (or some other such term, forwarded?) * rebased * merged The existence (and it being the default) of "merge --ff" makes that somewhat difficult, but in those cases we could and probably should just also say "advanced" (or whatever), since that's what happened, ditto a noop rebase.
Ævar Arnfjörð Bjarmason wrote: > > On Thu, Jun 24 2021, Felipe Contreras wrote: > > > Philip Oakley wrote: > >> On 24/06/2021 20:05, Felipe Contreras wrote: > >> > Philip Oakley wrote: > >> >> Hi Felipe, > >> >> On 24/06/2021 15:31, Felipe Contreras wrote: > >> >>> Philip Oakley wrote: > >> >>>> On 21/06/2021 18:52, Felipe Contreras wrote: > >> >>>>> --- a/Documentation/git-pull.txt > >> >>>>> +++ b/Documentation/git-pull.txt > >> >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > >> >>>>> ------------ > >> >>>>> A---B---C master on origin > >> >>>>> / > >> >>>>> - D---E---F---G master > >> >>>>> + D---E master > >> >>>>> ^ > >> >>>>> origin/master in your repository > >> >>>>> ------------ > >> >>>>> > >> >>>>> Then "`git pull`" will fetch and replay the changes from the remote > >> >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) > >> >>>>> -until its current commit (`C`) on top of `master` and record the > >> >>>>> -result in a new commit along with the names of the two parent commits > >> >>>>> -and a log message from the user describing the changes. > >> >>>>> +until its current commit (`C`) on top of `master`. > >> >>>>> + > >> >>>>> +After the remote changes have been synchronized, the local `master` will > >> >>>>> +be fast-forwarded to the same commit as the remote one, therefore > >> >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? > >> >>> No, there's multiple steps: > >> >> My key point was to 'quote' the fast-forward term. > >> > fast-forward is an English word [1], there's no need to quote it as if > >> > it weren't. > >> > >> You appear to be arguing that your "explain what is a fast-forward" > >> (subject line of the patch) doesn't need, within the patch, to explain > >> that it is about the term "fast-forward", being used in a Git specific > >> way... > > > > When you are trying to explain the meaning of a word it's generally > > better to not use that word in the explanation. For example if you are > > trying to explain "recursion", but you use "recursion" in the > > explanation, that kinds of defeats the purpose. > > > > So yes, in the sentence "the local `master` will be fast-forwarded to > > the same commit as the remote one", the verb "fast-forwarded" can easily > > be replaced with "advanced" and no meaning would be lost. > > > > The meaning of this "fast-forward" verb is the same as when you > > fast-forward a tape, and is not git-specific. > > Using quotes for a term like 'fast-forward' or some made up word like > 'qibbix' doesn't just serve the purpose of clarifying which ones are in > the dictionary, but also to establish that the quoted word is jargon > within the context of the documentation. > > If I invent a new and exciting way to cut grass I might say my new > machine 'shaves' the grass. The word "shave" is something I assume > everyone knows, but I'm making it clear that I'm referring to the > exciting mode of operation of my new death machine. > > So I think it Philip's suggestion makes sense. We're not talking about > how to fast-forward a tape, but what happens in git when we use that > term. No. In this particular sentence we are using fast-forward *precisely* in the same way as a tape. We haven't even talked about what constitutes a "fast-forward" in git jargon. Substitute the word "fast-forward", and the meaning remains intact: After the remote changes have been synchronized, the local `master` will be advanced to the same commit as the remote one, therefore creating a linear history. As I already explained. > As an aside after however many years of using git this is the first time > I made the connection to that usage of the term, I thought it was jargon > git invented. That's also something to consider, I was in your camp, but after thinking deeply about what would be a better term than "fast-forward" (advance, forward, boost), I realized that in fact "fast-forward" is perfectly fine because it already exists in English and conveys precisely the meaning we want: quickly advance to a desired position. > I've also actually seen an interacted with a tape record and VHS tape in > my lifetime, but I suspect many readers of this documentation have not. But they have pressed fast-forward on their Roku control, or whatever. Not only is it part of modern technology, but it's even used inside films, TV shows, and video games. See TV Tropes for dozens of examples where inside the film they fast-forward [1]. > This isn't something for your patch, but I wonder more generally if we > shouldn't consider moving away from the term entirely, and just say a > branch was one of: > > * advanced (or some other such term, forwarded?) > * rebased > * merged > > The existence (and it being the default) of "merge --ff" makes that > somewhat difficult, but in those cases we could and probably should just > also say "advanced" (or whatever), since that's what happened, ditto a > noop rebase. I already thought about it and I don't think so. The word "advanced" doesn't hint where, how much, or how quickly, could very well be just one commit forward. This is one of those rare occasions where I think the git project chose the perfect word. Cheers. [1] https://tvtropes.org/pmwiki/pmwiki.php/Main/FastForwardGag
On Fri, Jun 25 2021, Felipe Contreras wrote: > Ævar Arnfjörð Bjarmason wrote: >> >> On Thu, Jun 24 2021, Felipe Contreras wrote: >> >> > Philip Oakley wrote: >> >> On 24/06/2021 20:05, Felipe Contreras wrote: >> >> > Philip Oakley wrote: >> >> >> Hi Felipe, >> >> >> On 24/06/2021 15:31, Felipe Contreras wrote: >> >> >>> Philip Oakley wrote: >> >> >>>> On 21/06/2021 18:52, Felipe Contreras wrote: >> >> >>>>> --- a/Documentation/git-pull.txt >> >> >>>>> +++ b/Documentation/git-pull.txt >> >> >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is >> >> >>>>> ------------ >> >> >>>>> A---B---C master on origin >> >> >>>>> / >> >> >>>>> - D---E---F---G master >> >> >>>>> + D---E master >> >> >>>>> ^ >> >> >>>>> origin/master in your repository >> >> >>>>> ------------ >> >> >>>>> >> >> >>>>> Then "`git pull`" will fetch and replay the changes from the remote >> >> >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) >> >> >>>>> -until its current commit (`C`) on top of `master` and record the >> >> >>>>> -result in a new commit along with the names of the two parent commits >> >> >>>>> -and a log message from the user describing the changes. >> >> >>>>> +until its current commit (`C`) on top of `master`. >> >> >>>>> + >> >> >>>>> +After the remote changes have been synchronized, the local `master` will >> >> >>>>> +be fast-forwarded to the same commit as the remote one, therefore >> >> >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? >> >> >>> No, there's multiple steps: >> >> >> My key point was to 'quote' the fast-forward term. >> >> > fast-forward is an English word [1], there's no need to quote it as if >> >> > it weren't. >> >> >> >> You appear to be arguing that your "explain what is a fast-forward" >> >> (subject line of the patch) doesn't need, within the patch, to explain >> >> that it is about the term "fast-forward", being used in a Git specific >> >> way... >> > >> > When you are trying to explain the meaning of a word it's generally >> > better to not use that word in the explanation. For example if you are >> > trying to explain "recursion", but you use "recursion" in the >> > explanation, that kinds of defeats the purpose. >> > >> > So yes, in the sentence "the local `master` will be fast-forwarded to >> > the same commit as the remote one", the verb "fast-forwarded" can easily >> > be replaced with "advanced" and no meaning would be lost. >> > >> > The meaning of this "fast-forward" verb is the same as when you >> > fast-forward a tape, and is not git-specific. >> >> Using quotes for a term like 'fast-forward' or some made up word like >> 'qibbix' doesn't just serve the purpose of clarifying which ones are in >> the dictionary, but also to establish that the quoted word is jargon >> within the context of the documentation. >> >> If I invent a new and exciting way to cut grass I might say my new >> machine 'shaves' the grass. The word "shave" is something I assume >> everyone knows, but I'm making it clear that I'm referring to the >> exciting mode of operation of my new death machine. >> >> So I think it Philip's suggestion makes sense. We're not talking about >> how to fast-forward a tape, but what happens in git when we use that >> term. > > No. In this particular sentence we are using fast-forward *precisely* in > the same way as a tape. We haven't even talked about what constitutes a > "fast-forward" in git jargon. > > Substitute the word "fast-forward", and the meaning remains intact: > > After the remote changes have been synchronized, the local `master` > will be advanced to the same commit as the remote one, therefore > creating a linear history. > > As I already explained. I think even if you can accurately substitute the jargon it's worth quoting the jargon, to call out that it's jargon we're using quoted that place and others. Anyway, that doesn't have much to do with your isolated change, just a general comment on quoting v.s. not quoting invented v.s. borrowed/reused words. >> As an aside after however many years of using git this is the first time >> I made the connection to that usage of the term, I thought it was jargon >> git invented. That's also something to consider, > > I was in your camp, but after thinking deeply about what would be a > better term than "fast-forward" (advance, forward, boost), I realized > that in fact "fast-forward" is perfectly fine because it already exists > in English and conveys precisely the meaning we want: quickly advance to > a desired position. I think whatever term we're introducing will need git-specific explanation. E.g. because a "tree" is an everyday object our use of it needs explaining. >> I've also actually seen an interacted with a tape record and VHS tape in >> my lifetime, but I suspect many readers of this documentation have not. > > But they have pressed fast-forward on their Roku control, or whatever. > > Not only is it part of modern technology, but it's even used inside > films, TV shows, and video games. See TV Tropes for dozens of examples > where inside the film they fast-forward [1]. Unfortunately I haven't been able to non-fast-forward say the Game of Thrones TV show in such a way that the latest seasons makes any sense, since no amount of button mashing will merge their version with mine :) So I think in the context of us using this jargon to describe git-specific concepts the connection to reality is tenuous at best >> This isn't something for your patch, but I wonder more generally if we >> shouldn't consider moving away from the term entirely, and just say a >> branch was one of: >> >> * advanced (or some other such term, forwarded?) >> * rebased >> * merged >> >> The existence (and it being the default) of "merge --ff" makes that >> somewhat difficult, but in those cases we could and probably should just >> also say "advanced" (or whatever), since that's what happened, ditto a >> noop rebase. > > I already thought about it and I don't think so. The word "advanced" > doesn't hint where, how much, or how quickly, could very well be just > one commit forward. Hrm, we use fast-forward for N commits advanced, including N=1, or perhaps I'm misunderstanding you. > This is one of those rare occasions where I think the git project chose > the perfect word. Perhaps, it's not like I've got much in the way of a holistic world view with which to replace it. I do think "perfect" would do a few things it doesn't though, imagine reading about it for the first time and not making the connection to tapes. Is it an optimization? Is there a slow-forward? What if upstream rewound there branch and I merge, is that a merge-backwards? It's not immediately obvious how rebase/merge/fast-forward relate or if/when (e.g. merge sometimes being a merge-ff) they're incompatible concepts.
Ævar Arnfjörð Bjarmason wrote: > > On Fri, Jun 25 2021, Felipe Contreras wrote: > > > Ævar Arnfjörð Bjarmason wrote: > >> > >> On Thu, Jun 24 2021, Felipe Contreras wrote: > >> > >> > Philip Oakley wrote: > >> >> On 24/06/2021 20:05, Felipe Contreras wrote: > >> >> > Philip Oakley wrote: > >> >> >> Hi Felipe, > >> >> >> On 24/06/2021 15:31, Felipe Contreras wrote: > >> >> >>> Philip Oakley wrote: > >> >> >>>> On 21/06/2021 18:52, Felipe Contreras wrote: > >> >> >>>>> --- a/Documentation/git-pull.txt > >> >> >>>>> +++ b/Documentation/git-pull.txt > >> >> >>>>> @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is > >> >> >>>>> ------------ > >> >> >>>>> A---B---C master on origin > >> >> >>>>> / > >> >> >>>>> - D---E---F---G master > >> >> >>>>> + D---E master > >> >> >>>>> ^ > >> >> >>>>> origin/master in your repository > >> >> >>>>> ------------ > >> >> >>>>> > >> >> >>>>> Then "`git pull`" will fetch and replay the changes from the remote > >> >> >>>>> `master` branch since it diverged from the local `master` (i.e., `E`) > >> >> >>>>> -until its current commit (`C`) on top of `master` and record the > >> >> >>>>> -result in a new commit along with the names of the two parent commits > >> >> >>>>> -and a log message from the user describing the changes. > >> >> >>>>> +until its current commit (`C`) on top of `master`. > >> >> >>>>> + > >> >> >>>>> +After the remote changes have been synchronized, the local `master` will > >> >> >>>>> +be fast-forwarded to the same commit as the remote one, therefore > >> >> >>>> Perhaps s/be fast-forwarded/have been 'fast-forward'ed/ ? > >> >> >>> No, there's multiple steps: > >> >> >> My key point was to 'quote' the fast-forward term. > >> >> > fast-forward is an English word [1], there's no need to quote it as if > >> >> > it weren't. > >> >> > >> >> You appear to be arguing that your "explain what is a fast-forward" > >> >> (subject line of the patch) doesn't need, within the patch, to explain > >> >> that it is about the term "fast-forward", being used in a Git specific > >> >> way... > >> > > >> > When you are trying to explain the meaning of a word it's generally > >> > better to not use that word in the explanation. For example if you are > >> > trying to explain "recursion", but you use "recursion" in the > >> > explanation, that kinds of defeats the purpose. > >> > > >> > So yes, in the sentence "the local `master` will be fast-forwarded to > >> > the same commit as the remote one", the verb "fast-forwarded" can easily > >> > be replaced with "advanced" and no meaning would be lost. > >> > > >> > The meaning of this "fast-forward" verb is the same as when you > >> > fast-forward a tape, and is not git-specific. > >> > >> Using quotes for a term like 'fast-forward' or some made up word like > >> 'qibbix' doesn't just serve the purpose of clarifying which ones are in > >> the dictionary, but also to establish that the quoted word is jargon > >> within the context of the documentation. > >> > >> If I invent a new and exciting way to cut grass I might say my new > >> machine 'shaves' the grass. The word "shave" is something I assume > >> everyone knows, but I'm making it clear that I'm referring to the > >> exciting mode of operation of my new death machine. > >> > >> So I think it Philip's suggestion makes sense. We're not talking about > >> how to fast-forward a tape, but what happens in git when we use that > >> term. > > > > No. In this particular sentence we are using fast-forward *precisely* in > > the same way as a tape. We haven't even talked about what constitutes a > > "fast-forward" in git jargon. > > > > Substitute the word "fast-forward", and the meaning remains intact: > > > > After the remote changes have been synchronized, the local `master` > > will be advanced to the same commit as the remote one, therefore > > creating a linear history. > > > > As I already explained. > > I think even if you can accurately substitute the jargon it's worth > quoting the jargon, to call out that it's jargon we're using quoted that > place and others. But in this sentence it is not jargon. Do you want me to send another patch using "advance" instead of "fast-forward"? > >> As an aside after however many years of using git this is the first time > >> I made the connection to that usage of the term, I thought it was jargon > >> git invented. That's also something to consider, > > > > I was in your camp, but after thinking deeply about what would be a > > better term than "fast-forward" (advance, forward, boost), I realized > > that in fact "fast-forward" is perfectly fine because it already exists > > in English and conveys precisely the meaning we want: quickly advance to > > a desired position. > > I think whatever term we're introducing will need git-specific > explanation. E.g. because a "tree" is an everyday object our use of it > needs explaining. But in this specific sentence it's not a git-specific explanation. It's using as few git-specific concepts, and as many non-git-specific concepts, to explain a git-specific concept. > >> I've also actually seen an interacted with a tape record and VHS tape in > >> my lifetime, but I suspect many readers of this documentation have not. > > > > But they have pressed fast-forward on their Roku control, or whatever. > > > > Not only is it part of modern technology, but it's even used inside > > films, TV shows, and video games. See TV Tropes for dozens of examples > > where inside the film they fast-forward [1]. > > Unfortunately I haven't been able to non-fast-forward say the Game of > Thrones TV show in such a way that the latest seasons makes any sense, > since no amount of button mashing will merge their version with mine :) But they used the fast-forward gag in Deadpool. Why? Because Hollywood writers know their audience, and they know virtually everyone is aware of what fast-forwarding is. Even the simplest remote controllers have a fast-forward button. > So I think in the context of us using this jargon to describe > git-specific concepts the connection to reality is tenuous at best Why do you think it was named "fast-forward" in the first place? And not say "look-announce"? I still haven't seen an argument as to why Deadpool writers (and many others) would have used this concept if it weren't mainstream. > >> This isn't something for your patch, but I wonder more generally if we > >> shouldn't consider moving away from the term entirely, and just say a > >> branch was one of: > >> > >> * advanced (or some other such term, forwarded?) > >> * rebased > >> * merged > >> > >> The existence (and it being the default) of "merge --ff" makes that > >> somewhat difficult, but in those cases we could and probably should just > >> also say "advanced" (or whatever), since that's what happened, ditto a > >> noop rebase. > > > > I already thought about it and I don't think so. The word "advanced" > > doesn't hint where, how much, or how quickly, could very well be just > > one commit forward. > > Hrm, we use fast-forward for N commits advanced, including N=1, or > perhaps I'm misunderstanding you. For example in the context of a film, "advance" could easily mean move one second ahead, or even unpause. Fast-forward on the other hand can't be used that way, it implies moving quickly many seconds. > > This is one of those rare occasions where I think the git project chose > > the perfect word. > > Perhaps, it's not like I've got much in the way of a holistic world view > with which to replace it. > > I do think "perfect" would do a few things it doesn't though, imagine > reading about it for the first time and not making the connection to > tapes. Is it an optimization? Is there a slow-forward? What if upstream > rewound there branch and I merge, is that a merge-backwards? > > It's not immediately obvious how rebase/merge/fast-forward relate or > if/when (e.g. merge sometimes being a merge-ff) they're incompatible > concepts. I don't think there's any word in the English language that would magically place the fully-formed concept of the git's fast-forward in the reader's mind. That applies for all concepts though. A git "branch" needs to be explained, just knowing what a branch is in English isn't enough, and if nobody has used a SCM, the same for a "commit". In psychology of learning there's a concept called chunking [1]. In order to understand what the word "economy" means, you need to learn many other concepts before, including the concept of "market", and for that you need many others, including "money", and so on. Very complex concepts are constituted by multiple big sub-chunks. To explain the git-specific concept of a fast-forward, it's in our best interest to reuse chunks that are already in the zeitgeist of the culture, including the non-git-specific concept of fast-forwarding. This patch is not simply saying a "fast-forward" is a fast-forward. It's explaining the git-specific fast-forward by capitalizing from the general knowledge fast-forward, which is so mainstream it's even used in Hollywood. Cheers. [1] https://en.wikipedia.org/wiki/Chunking_(psychology)
> From: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > Sent: 25 June 2021 11:59 > >> So I think it Philip's suggestion makes sense. We're not talking > >> about how to fast-forward a tape, but what happens in git when we use > >> that term. > > > > No. In this particular sentence we are using fast-forward *precisely* > > in the same way as a tape. We haven't even talked about what > > constitutes a "fast-forward" in git jargon. > > > > Substitute the word "fast-forward", and the meaning remains intact: > > > > After the remote changes have been synchronized, the local `master` > > will be advanced to the same commit as the remote one, therefore > > creating a linear history. > > > > As I already explained. > > I think even if you can accurately substitute the jargon it's worth quoting the > jargon, to call out that it's jargon we're using quoted that place and others. > > Anyway, that doesn't have much to do with your isolated change, just a > general comment on quoting v.s. not quoting invented v.s. borrowed/reused > words. > > >> As an aside after however many years of using git this is the first > >> time I made the connection to that usage of the term, I thought it > >> was jargon git invented. That's also something to consider, > > > > I was in your camp, but after thinking deeply about what would be a > > better term than "fast-forward" (advance, forward, boost), I realized > > that in fact "fast-forward" is perfectly fine because it already > > exists in English and conveys precisely the meaning we want: quickly > > advance to a desired position. > > I think whatever term we're introducing will need git-specific explanation. > E.g. because a "tree" is an everyday object our use of it needs explaining. > > >> I've also actually seen an interacted with a tape record and VHS tape > >> in my lifetime, but I suspect many readers of this documentation have > not. > > > > But they have pressed fast-forward on their Roku control, or whatever. > > > > Not only is it part of modern technology, but it's even used inside > > films, TV shows, and video games. See TV Tropes for dozens of examples > > where inside the film they fast-forward [1]. > > Unfortunately I haven't been able to non-fast-forward say the Game of > Thrones TV show in such a way that the latest seasons makes any sense, > since no amount of button mashing will merge their version with mine :) > > So I think in the context of us using this jargon to describe git-specific > concepts the connection to reality is tenuous at best > > This is one of those rare occasions where I think the git project > > chose the perfect word. I agree. > Perhaps, it's not like I've got much in the way of a holistic world view with > which to replace it. > > I do think "perfect" would do a few things it doesn't though, imagine reading > about it for the first time and not making the connection to tapes. Is it an > optimization? Is there a slow-forward? What if upstream rewound there > branch and I merge, is that a merge-backwards? > > It's not immediately obvious how rebase/merge/fast-forward relate or > if/when (e.g. merge sometimes being a merge-ff) they're incompatible > concepts. On the one hand, I think fast-forward is an entirely suitable term for git to use, based on what it does. Instantaneously moving the branch head pointer forward to the new head On the other hand I think it is distinctly different from the use with transport controls for linear media (ie tape - video or audio). For all of them fast-forward moves the play/record point relative to the media, maybe to the end (or to "now"), maybe not. There may or may not be a cueing play that happens while the tape is moving. For a modern stream (eg podcast) player, such as BBC Sounds (via its web-site) there is no fast-forward control. There is play/pause, +20 and -20 seconds, go to the start of the stream and (for live broadcasts) go to now. The latter is very close to Git's fast-forward, but is not labelled as such. There is also a time-line, where the user can go to an arbitrary point in time and play from there. Hardware players do have fast-forward controls, even for streams, or files. So, yes, the term is very widely known in the wider world (even for those who didn't grow up with tape). And yes, irrespective of the above, it makes complete sense for git's usage. Regards, Richard.
Kerry, Richard wrote: > > > From: Ævar Arnfjörð Bjarmason <avarab@gmail.com> > > Sent: 25 June 2021 11:59 > > Perhaps, it's not like I've got much in the way of a holistic world view with > > which to replace it. > > > > I do think "perfect" would do a few things it doesn't though, imagine reading > > about it for the first time and not making the connection to tapes. Is it an > > optimization? Is there a slow-forward? What if upstream rewound there > > branch and I merge, is that a merge-backwards? > > > > It's not immediately obvious how rebase/merge/fast-forward relate or > > if/when (e.g. merge sometimes being a merge-ff) they're incompatible > > concepts. > > On the one hand, I think fast-forward is an entirely suitable term for git to use, based on what it does. Instantaneously moving the branch head pointer forward to the new head > On the other hand I think it is distinctly different from the use with transport controls for linear media (ie tape - video or audio). > For all of them fast-forward moves the play/record point relative to the media, maybe to the end (or to "now"), maybe not. There may or may not be a cueing play that happens while the tape is moving. > For a modern stream (eg podcast) player, such as BBC Sounds (via its web-site) there is no fast-forward control. There is play/pause, +20 and -20 seconds, go to the start of the stream and (for live broadcasts) go to now. The latter is very close to Git's fast-forward, but is not labelled as such. There is also a time-line, where the user can go to an arbitrary point in time and play from there. > Hardware players do have fast-forward controls, even for streams, or files. Yes, but regardless of that for whatever reason it's already part of the culture, and people are using fast-forward irrespective of the original meaning: "They fast-forward to present day ten years later, where he has been hospitalized and is on life support." [1] "So then fast-forward to now and, like, six months ago, they found the script and called me up." [2] This is similar to what happened with the floppy disk icon. New generations may have no idea what it originally meant, regardless of that today it means "save". Except the fast-forward button still exists in many remote controls. Same with other concepts like carbon copy. I'm not sure if newer generations have ever seen an actual physical carbon copy take place. Or a physical bookmark. Words evolve beyond their original meaning, and today I think that has already happened with fast-forward. > So, yes, the term is very widely known in the wider world (even for those who didn't grow up with tape). > And yes, irrespective of the above, it makes complete sense for git's usage. Indeed. [1] https://en.wikipedia.org/wiki/I_Need_a_Doctor [2] https://en.wikipedia.org/wiki/Predators_(film)
Felipe Contreras wrote: > Yes, but regardless of that for whatever reason it's already part of the > culture, and people are using fast-forward irrespective of the original > meaning: > > "They fast-forward to present day ten years later, where he has been > hospitalized and is on life support." [1] > > "So then fast-forward to now and, like, six months ago, they found the > script and called me up." [2] Hmmm, Fast-forward 6 years and all this code has been substantially overhauled by several folks over the years https://lore.kernel.org/git/CAPMMpohp6+jW2C0ewfYEp3rrwbKSqGVa94LRgQDcKJvYmiANuA@mail.gmail.com/
diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt index 5c3fb67c01..142df1c4a1 100644 --- a/Documentation/git-pull.txt +++ b/Documentation/git-pull.txt @@ -41,16 +41,41 @@ Assume the following history exists and the current branch is ------------ A---B---C master on origin / - D---E---F---G master + D---E master ^ origin/master in your repository ------------ Then "`git pull`" will fetch and replay the changes from the remote `master` branch since it diverged from the local `master` (i.e., `E`) -until its current commit (`C`) on top of `master` and record the -result in a new commit along with the names of the two parent commits -and a log message from the user describing the changes. +until its current commit (`C`) on top of `master`. + +After the remote changes have been synchronized, the local `master` will +be fast-forwarded to the same commit as the remote one, therefore +creating a linear history. + +------------ + D---E---A---B---C master, origin/master +------------ + +However, a non-fast-forward case looks very different: + +------------ + A---B---C origin/master + / + D---E---F---G master +------------ + +If there are additional changes in the local `master`, it's +not possible to fast-forward, so a decision must be made how to +synchronize the local, and remote brances. + +In these situations `git pull` will warn you about your possible +options, which are either merge (`--no-rebase`), or rebase (`--rebase`). +However, by default it will continue doing a merge. + +A merge will create a new commit with two parent commits (`G` and `C`) +and a log message describing the changes, which you can edit. ------------ A---B---C origin/master @@ -58,8 +83,11 @@ and a log message from the user describing the changes. D---E---F---G---H master ------------ +Once the merge commit is created (`H`), your local `master` branch has +incorporated the changes of the remote `master` branch. + See linkgit:git-merge[1] for details, including how conflicts -are presented and handled. +are presented and handled, and also linkgit:git-rebase[1]. In Git 1.7.0 or later, to cancel a conflicting merge, use `git reset --merge`. *Warning*: In older versions of Git, running 'git pull' @@ -248,7 +276,8 @@ version. SEE ALSO -------- -linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-config[1] +linkgit:git-fetch[1], linkgit:git-merge[1], linkgit:git-rebase[1], +linkgit:git-config[1] GIT ---
We want users to know what is a fast-forward in order to understand the default warning. Let's expand the explanation in order to cover both the simple, and the complex cases with as much detail as possible. Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com> --- Documentation/git-pull.txt | 41 ++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-)