Re: Git Books
On 2008.12.06 03:58:28 -0800, Scott Chacon wrote:
Show 8 quoted lines
> 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
Scott Chacon
