Re: PATCH: improve git switch documentation

Felipe Contreras [off-list ref] writes:

Sergey Organov wrote:

quoted

Martin [off-list ref] writes:

quoted

On 01/07/2021 00:59, Junio C Hamano wrote:

quoted

Martin [off-list ref] writes:

quoted

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.

quoted

quoted

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

I see why "branch head", as you later introduce "branch tail", but a
branch (of a plant) has no "head" (nor "tail"), right? BTW, how the base
of a plant branch is called in English, and how one finds "branch tail"
on a real tree anyway? I mean, there are probably a few of them, at
every fork. In Git it's even more vague, as a branch could logically
begin at any place, not necessarily at a fork point.

OTOH, "head" and "tail" are obviously taken from CS "list" concept, and,
provided "chain" == "list", it does make sense. And then we have 'HEAD'
that points to the current branch tip anyway.

Dunno, in fact I don't have any preference among "tip" and "head".

As for branch tail, I do have convention of marking start of a
long-standing branch with corresponding tag, where branch "foo" has
corresponding "foo-bp" tag marking its "branch point". Recently I
started to mark start of feature branch with yet another branch "foo-bp"
rather than tag, "foo" being set to track "foo-bp", that allows to
automate rebasing of "foo" against correct base.

Thanks,
-- 
Sergey Organov