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, nickname, pull, refspec, repository, remote, remote-ref, url
That’s a lot of knowledge required in order to understand this error message about a common beginner mistake. And rhetorically, 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 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.
Dogweather 
`man gitglossary` should give you the information you’re looking for. I found that man page from inside the git manpage.
I’m finding the “Git Reference” to be a big help. http://gitref.org/
And attempting to parse the man pages…
1) The refspec is the path that you’ve given git (explicitly or, more likely, implicitly via another command) for this repo. It tells git what branches you want to pull.
2) the nickname is the alias for the repository. You’ve probably set up “origin” to be the nickname for your remote repository.
3) in Git, a pull is effectively an alias for fetch and merge. That’s why you’re getting merge-speak.
Adding all of this up, Git is complaining because you’re not telling it what branch you want to pull (fetch and merge). Imagine you’re on branch feature1, and you say git pull. Git pull what? git pull origin master? git pull other-remote other-branch?
So you need to tell git: git pull origin feature1
Now, back to your refspec. The reason git was blathering about that is because you can set up your refspec to tell git what git pull means by default. It could be handy to do this for branches you’re pulling a lot- like the master branch of the origin repository.
Unfortunately, I think you’re dead on with your criticism of the docs. More specifically, I think the docs are wonderful, but the terminology is confusing.
Stick with it, it’s worth your time 🙂