Re: master^ is not a local branch -- huh?!?

["J. Bruce Fields" <bfields@fieldses.org>]

On Tue, Feb 02, 2010 at 02:04:22PM -0800, Ron Garret wrote:
> In article <20100202191942.GB9628@fieldses.org>,
>  "J. Bruce Fields" <bfields@fieldses.org> wrote:
> 
> > My memory is that I'd seen the word "branch" used for both meanings (a
> > linear piece of history, and a ref under ref/heads/), so figured we
> > needed terms for both.
> > 
> > But then I didn't really use that distinction anywhere.  On a quick skim
> > the only instance I can see of the first sense is in
> > http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#counting-com
> > mits-on-a-branch,
> > which could probably be reworded.
> > 
> > It still may be worth acknowledging the confusion; e.g., something like:
> > 
> > 	In the above diagram, "A", "B", and "master" are all references
> > 	to a point in history.  We call all three "branches".
> > 
> > 	Informally, the word "branch" is sometimes also used to the
> > 	entire line of development leading up to one of these points,
> > 	or, more generally, to any individual line of development.  But
> > 	when speaking about git, a "branch" (or "branch head") will
> > 	always be a reference to a point in history, and in particular a
> > 	reference which may be advanced to new commits by future
> > 	development.
> > 
> > Eh, I don't know if that's helpful; maybe that section could just be
> > deleted.  Or replaced by a more general discusion of the ref/ namespace.
> 
> FWIW, I find the above verbiage to to be very clear, much better than 
> what is there now.  You might also add that branches are almost exactly 
> the same as tags.  The only difference (AFAIK) is that tags get dragged 
> along by commits and resets and tags don't.

Might also be worth considering whether this:

	http://kernel.org/pub/software/scm/git-core/docs/user-manual.html#how-git-stores-references

or some other general introduction to refs, should be moved to appear
earlier in the manual.

Apologies, though, I can't volunteer for now; if you'd like any of this
to happen, I'd recommend sending Junio patches.  (I'll try to read them
if you cc: me.)

--b.