Re: [PATCH 1/2] doc: pull: explain what is a fast-forward

> 
> 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.

> >> 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 :)

> >> 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.