Re: PATCH: improve git switch documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 7, 2021, 18:34 UTC
Message-ID: <60e5f3981de5f_301437208bc@natae.notmuch>
In-Reply-To: <87wnqaclz8.fsf@osv.gnss.ru>

Sergey Organov wrote:

Show 31 quoted lines

> Martin <git@mfriebe.de> writes:
> > On 01/07/2021 00:59, Junio C Hamano wrote:
> >> Martin <git@mfriebe.de> writes:
> >>
> >>> And yes, for the documentation, it *should* be clear that, removing a
> >>> branch, removes the
> >>> commits on it.
> >>> But then it must be said, that the branch is first removed. That is
> >>> not currently the case.
> >> Sorry, but I still do not see how it makes any difference if the
> >> branch is first removed and then made to point at somewhere else, or
> >> the branch gets just moved without any explicit or impolicit
> >> removal.  A branch cannot point at two different commits at the same
> >> time, so the end result is that the commit at the old tip is no
> >> longer pointed at by the branch after the update.
> >
> > Well all very obvious, if you know git well.
> >
> > Let's take a step back. How exactly is the word "branch" actually defined? Well it does not matter.
> > What matters is, how the word is used.
> > What does a person mean, when they speak of the branch?
> >
> > And the answer is, it's not always clear.
> 
> Yep. The "branch" may mean a "chain of commits" or a "symbolic reference
> to the tip of the branch", or even both, depending on the context.
> 
> It's somewhat similar to "file" vs "file name" in UNIX. You in fact
> don't remove files in UNIX, you remove file names that refer to files
> (entities on disk), yet "remove file" and "rename file" are often
> used, even though they are not technically correct.

It's not even specific to computers, it's semantics of identifiers.

You can say John is not a person, "John" is the *name* of a person, the person is constituted by cells and so on.

Most of the time it's not particularly useful to think on those terms, but sometimes it useful in the sense that we can confidently say "master" is not a branch, is the name of a branch.

In Mercurial branches are more like commit labels, so it's easy to see the difference between a branch (a collection of commits), and a branch name. In Git it's trickier because the branch is a pointer, and it doesn't make much sense to think of a pointer without a name, but strickly speaking they are different.

Show 25 quoted lines

> > But true, my attempt on adding "the old branch is removed" does not either.
> > So not sure which wording will do best.
> > Probably
> >        "Creates a new empty branch at <start point>"
> >
> > Even though "empty" may be a sloppy usage too....
> >
> 
> Yes, it's sloppy. There are no empty branches from Git point of view, so
> this is not an option for proper documentation. Any branch has at least
> one commit, the one the branch name is pointing at. It's entirely user
> interpretation how many of the commits from the chain the Git branch has
> they consider their branch "contains".
> 
> Overall, if we aim at clear documentation, we need to define our
> documentation terms as precise as possible, and then use them
> consistently.
> 
> For example:
> 
> "branch": a chain of commits
> 
> "branch tip": the most recent commit in a branch
> 
> "branch name": specific type of symbolic reference pointing to a branch tip

Completely agree on all three (although I would call it "branch head", not "branch tip").

Sometimes we can use a shortcut and say "master" is a branch, as we do in everyday language when we say "John" is a person, but when we are strict we have to remember what's behind that shortcut.

Slightly related although a little bit off-topic is the fact the *only* thing Mercurial can do that Git can't is to find the branching point of a branch [1] (I have really tried, it's truly not possible).

The *only* way it would be possible is by introducing a new concept: "branch tail". I did implement patches for that (you could reference to it with master@{tail}).

It is related to this topic because if we had a branch head, and a branch tail, then you could not automatically assume the branch is the branch head.

So even though most of the documentation currently conflates the two concept, that doesn't mean the user does as well.

[1] https://stackoverflow.com/questions/1527234/finding-a-branch-point-with-git

-- 
Felipe Contreras