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:

quoted

On Thu, Jun 24 2021, Felipe Contreras wrote:

quoted

Philip Oakley wrote:

quoted

On 24/06/2021 20:05, Felipe Contreras wrote:

quoted

Philip Oakley wrote:

quoted

Hi Felipe,
On 24/06/2021 15:31, Felipe Contreras wrote:

quoted

Philip Oakley wrote:

quoted

On 21/06/2021 18:52, Felipe Contreras wrote:

quoted

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

quoted

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.

quoted

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

quoted

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.