That one little confusing thing about the Git version control system
Git and github are awesome pieces of software. Last year, I happily switched from subversion to git just like, years ago, I switched from CVS to subversion. Another evolutionary step. I use github for lots of reasons. The biggest is that it’s the best front-end to git that I’ve found. And so now I use git+github for 15 or so projects; some open source like HTTP Assertions, and some private code, like the OregonLaws.org web app.
The one little problem
Everything goes along happily until git decides you need some help. And so, in a fit of well intentioned verbosity, git coughs up three terminology-packed paragraphs of text that we’ve all seen:
You asked me to pull without telling me which branch you want to merge with, and 'branch.newlayout.merge' in your configuration file does not tell me either. Please specify which branch you want to merge on the command line and try again (e.g. 'git pull <repository> <refspec>'). See git-pull(1) for details.
If you often merge with the same branch, you may want to configure the following variables in your configuration file:
branch.newlayout.remote = <nickname>
branch.newlayout.merge = <remote-ref>
remote.<nickname>.url = <url>
remote.<nickname>.fetch = <refspec>
I collected the following git-specific terms from this one message:
branch, fetch, git-pull, merge, newlayout, nickname, pull, refspec, repository, remote, remote-ref, url
What’s the difference between a <refspec> and a <remote-ref>? Between a <repository> and a <nickname>? Between a pull and a merge? (I asked for a pull, but git’s giving me merge info.)
My guess: several of these terms are used interchangeably, and git’s docs should be made more consistent. Note how the terms in the text paragraphs do not match the terms in the config file template.
Problem #2: The second paragraph says to add the info to the config file. But the info isn’t in config file format; it’s closer to command line
git config format.