Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

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.

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