Re: [DRAFT] Branching and merging with git

I'm working on incorporating all of the comments I've received, so thank you all!

(BTW, the reason I didn't document git-describe is that I didn't know about it! You fixed the latter, so I'll fix the former.)

I'm glad if others like it, but I was really scratching my own itch. I'm still wrapping my head around how to work with git, and writing this was my own learning experience.

Even writing it out in full rather than as rougher notes wasn't
an entirely unselfish act; it ensures:
1) I don't leave some important assumption unstated; that's the
   type most likely to be wrong, and
2) If I can get it good enough to post publicly, I'll get all the
   experts to fact-check it for me.

As for the target audience, it's basically someone who's read git(1) and knows what a VCS is supposed to do, but has a CVS/SVN mindset. The emphasis is on branching and merging because that's the big "mental mode" difference in the way that git works.

For anyone else documenting git, I recommend describing "what if I make a mistake" early. It was a bit of a revelation to realize that there's not much point to "git pull --no-commit" because it's so easy to undo.

Just a couple of questions:

We seem to have developed a consensus on the desirability of allowing HEAD to point outside refs/heads, postponing the check until commit/merge time. (At least, junkio and Linus seemed to like it.)

I proposed it, so I get to write it, but you notice I have a whole section on how to work around the lack of that feature, so if someone feels like picking up the baton while I'm still writing docs, it would simplify things.

I'd like to learn more about the zillion options to git-log. If people feel like sharing useful incantations, it would be be very helpful to give a concrete example of its usefulness, preferably within the git history itself.

(Are there any octopus merges in git's history?  If not, could I ask