Re: PATCH: improve git switch documentation

[Felipe Contreras <felipe.contreras@gmail.com>]

Junio C Hamano wrote:
> 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.

> 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