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

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