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

On Tue, Feb 02, 2010 at 02:04:22PM -0800, Ron Garret wrote:

In article [ref],
 "J. Bruce Fields" [off-list ref] wrote:

quoted

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.