Re: PATCH: improve git switch documentation

[Sergey Organov <sorganov@gmail.com>]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Sergey Organov wrote:
>> 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.
>
>> > 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