Re: PATCH: improve git switch documentation

Martin [off-list ref] writes:

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.

To me it's essential feature of Git that when you, say, "remove branch",
you only delete the symbolic reference, not any chain of commits, and
documentation should not contradict this where it uses the term
"branch".

In the above conversation, we use "branch" to speak of the "pointer to a single commit".
We do not include any commits, when speaking of the "branch".
(And this is how it is used in the docs, as far as I can find)

However a lot of people use "branch" to refer to the commits within.
"Push a branch to a remote". That obviously means the objects (e.g. commits) in the branch.
The doc says (and yes I am getting a bit picky here)

quoted

quoted

quoted

Updates remote refs using local refs, while sending objects necessary to complete the given refs.

"complete the given ref". The ref is given by the branch, and
completing means afaik "to make something part of"
Maybe a mistake made, because "branch" is (according to my
observation) so commonly (mis-)used to include the objects.

Anyway, can we agree, that there are people who  (mistakenly)
use/understand "branch" as including the objects?
Enough people to call it a "common mistake".
If so, then we should not ignore this.

I don't see this as a mistake. A branch is a chain of commits. It's just
using of short term "branch" without further clarification that could
lead to confusion.

With this use of "branch" in mind, (re-)creating an existing  branch
on a new startpoint, does to the inexperienced user read like a
rebase. It recreates all the commits. The fact that as an experienced
user, I shake my head in disbelief, does not change this.

Some understanding of underlying Git model is inevitable here. I'd
suggest to use "branch name" and other means to disambiguate description
instead of trying to describe what happens using wrong underlying model.

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

It's then up to the user to learn a few simple basics required for
proper understanding of documentation and behavior.

Thanks,

-- 
Sergey Organov

Sergey Organov wrote:

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

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