Re: [DRAFT] Branching and merging with git

[linux@horizon.com]

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