Re: Git Books

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2008.12.06 03:58:28 -0800, Scott Chacon wrote:
> So, since I'm near the beginning of this process, I was wondering if
> the group had any feedback as to what might be super helpful to
> include.  I mean, I have a pretty good layout and all, but if you
> wanted to point me to some threads that tend to crop up in the mailing
> list and IRC channel from relative newcomers that I might be able to
> nip in the bud, I would like to.  I'm addressing the stuff that _I_
> hear a lot, and I'm scanning the IRC logs and list for topics, but I
> figured many of you must answer the same questions all the time, too.

Just some random thoughts:

Please explain HEAD early on, and what it actually means. I've seen
quite a number of people understanding HEAD as, for example, a magic
keyword, a branch property, or a _direct_ reference to the latest commit
on the branch they have checked out. Especially the last one has really
confused the hell out of some people when they came across the concept
of a detached HEAD.

Explaining remote tracking branches early on, say after the first
"clone" is also important I guess. A number of readers will probably
just "dive in" when they learned a few commands and clone some random
repo to start playing. Unless Murphy lets us down, they'll clone a repo
that has multiple branches and will sit there, wondering how to get one
of the branches that only exist as remote tracking branches in their
repo.

And for commands, it's IMHO best to always start with the "full blown"
form, and only then, after introducing the command and what it does,
start to talk about short forms and how you can leave out some arguments
and fall back to defaults.

For example:

rebase:
Start with "rebase --onto <onto> <upstream> <branch>" and how that takes
the commits from <upstream>..<branch> and "replays" them on top of
<onto>. In my experience, starting with that version and showing how it
affects the commit DAG helps people to actually understand what happens,
while a plain "git rebase master" seems like pure magic to some, because
you can't even use the arguments to explain why and where things are
placed, or you start telling how those are all defaults, and then have
to explain everything all over again, when you use the explicit form for
more complicated things and people seem to get confused by that.

fetch:
Include refspecs in the first examples and show how a missing rhs causes
the fetched stuff to be stored in FETCH_HEAD. And only then go on to
tell that remotes usually have a default refspec in their config, and
that you can thus omit the refspecs when you fetch from a remote.

push:
refspecs again. Maybe start with pushing a single branch/tag/whatever,
explicitly, eg. "git push origin refs/heads/master:refs/heads/master",
and only then introduce the DWIM stuff like "git push origin master".
Same thing for the default ":" refspec, please mention what that refspec
means and that it is the default when no refspec is given (either on the
command line or in the config). A lot of people don't seem to know about
refspecs at all, and the "matching branch names" refspec is IMHO worth
being mentioned, as I've seen a bunch of questions lately that could be
answered by explaining that. For example, updating matching branches and
pushing a new tag at once, or having a push config that pushes one or
more branches to differently named branches on the remote, but using the
name matching for all other. And personally, I also like "git push
origin : v1.2.3" better than pushing twice or naming my branches
explicitly :-)

Björn