Re: PATCH: improve git switch documentation

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Jul 7, 2021, 18:47 UTC
Message-ID: <60e5f6cd6afa9_3014372088c@natae.notmuch>
In-Reply-To: <xmqqh7hersgp.fsf@gitster.g>

Junio C Hamano wrote:

Show 17 quoted lines

> Martin <git@mfriebe.de> writes:
> 
> > 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 do not think it is a mistake at all.  In a history where the
> branch B points at commit Z, we do say the branch contains commits Z
> and Y and we do say the branch does not contain commits X or W, for
> example.
> 
>                  W---X
>                 /
>         ---o---V---Y---Z
>                        ^ we're here (branch B)
>

There's a difference between saying the branch *is* commits A, B, ... Y, Z, and the branch *contains* commits ...

In Git only the latter is true, because technically the branch is a pointer. But in Mercurial both are true.

Show 5 quoted lines

> I think the source of the confusion is the <start point>.  It does
> not change what the explanation wants to say at all if we changed
> it to <end point>.  It is where the branch's tip ends up to be after
> "git branch -f" (or "git switch -C") finishes, so it might even be
> technically more correct.

Indeed.

However, there's a better alternative than "end point": head. Sure, the unfortunate naming of the current branch as HEAD makes this slightly confusing, but that's really what it is.

If you change the branch head *everyone* understands the the branch itself is changed, and the commits that are part of the branch are different.

-- 
Felipe Contreras