Re: PATCH: improve git switch documentation

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

Martin wrote:
> 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?

That is a good point.

> And the answer is, it's not always clear.

Indeed.

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

This is how the term "branch" is used in git lingo.

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

Yes.

> 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 wouldn't even call it a mistake.

Other SCMs, like Mercrual, do use this second meaning: the branch is the
specific commits that constitute that branch.

Can we really say user thinking that way is a mistake? I'm sure
Mercurial users would say git using the first notion is the a mistake.


It is a bigger mental load to be thinking in the two meanings at the
same time while writing the documentation, but if we really want to
reach the vast majority of users we do need to consider that the user
might be thinking in terms of the second notion.

-- 
Felipe Contreras