confusion over the new branch and merge config

OK I know I'm a total idiot and honnestly I didn't look at the code implementation at all because I don't expect newbies to even look there.

But here's some pitfalls I'm sure people are likely to encounter...

$ git clone git://git.kernel.org/pub/scm/git/git.git git
Initialized empty Git repository in /home/nico/test/git/.git/
remote: Generating pack...
remote: Done counting 34527 objects.
remote: Deltifying 34527 objects.
remote:  100% (34527/34527) done
Indexing 34527 objects.
remote: Total 34527, written 34527 (delta 23920), reused 34111 (delta 23623)
 100% (34527/34527) done
Resolving 23920 deltas.
 100% (23920/23920) done
Checking files out...
 100% (748/748) done

[ wooh! I feel good ]

$ cd git
$ git branch
* master

[ Hmmm... there used to be many more (remote) branches before.  Where 
  are they? Looking into .git/refs I see a remote/ directory and all 
   remote branches are there.  But I'm cheating now because a newbie 
   might not even think of looking there.

   Ah? there is -a and -r options to git-branch.  Fair enough. ]

$ git branch -r
* master
  origin/HEAD
  origin/html
  origin/maint
  origin/man
  origin/master
  origin/next
  origin/pu
  origin/todo
$ git checkout next
error: pathspec 'next' did not match any file(s) known to git.
Did you forget to 'git add'?

[ WTF!?!?  This definitely used to work before.  OK it is listed as
  "origin/next" so let's try to be consistent. ]

$ git checkout origin/next
git checkout: to checkout the requested commit you need to specify
              a name for a new branch which is created and switched to

[ Hmmmmmmmm.... /me stares at the message wondering.
  I just want to _see_ and maybe _install_ the code from "next". ]

$ git checkout origin/next local_next error: pathspec 'local_next' did not match any file(s) known to git. Did you forget to 'git add'?

[ But it just said to me above that I needed to provide a name for the 
  branch to be switched to...  Why doesn't it just work? F***ing tool!

  OK I'll use my git knowledge and cheat again. ]

$ git checkout -b local_next origin/next

This is I think a good example where user experience might still be improved. First the message about "providing a name for a new branch" could certainly be less anbigous.

Then the "next" branch name could possibly be made to work without the "origin/" if there is no conflict?

And there was a discussion about allowing checkouts to be made from a remote branch but not allowing any commit on it. What happened of this idea?

Now that I have my local_next branch, I want it to be kept up to date when performing a pull. Before the "next" branch sort of was always updated, but now it is a separate thing I cannot see directly and I need to pull it in my local version.

$ git pull origin/next fatal: The remote end hung up unexpectedly Cannot get the repository state from git://git.kernel.org/pub/scm/git/git.git/next

[ WTF?  Where that ...pub/scm/git/git.git/next comes from?  Hmmm... ]

$ git pull next fatal: 'next': unable to chdir or not a git archive fatal: The remote end hung up unexpectedly Cannot get the repository state from next

[ ... an even more interesting set of error messages.

  Yeah, Linus says you must use git-pull . blah syntax. ]

$ git pull . next error: no such remote ref refs/heads/next Fetch failure: . $ git pull . origin/next error: no such remote ref refs/heads/origin/next Fetch failure: .

[ F**K YOU STUPID TOOL !!!  OK let's cheat a bit again. ]

$ git pull . remotes/origin/next Already up-to-date.

[ Woooh!  But since I always hated this syntax let's try merge instead. ]

$ git merge origin/next Already up-to-date.

OK here again various error messages could be improved. The fact that a remote connection was established in some cases is really dubious. And git-pull not accepting "origin/next" is IMHO a bug.

Well well... But I don't want to perform this two-step git-pull+git-merge all the time. So let's have a look at this promising warning:

$ git pull origin
Warning: No merge candidate found because value of config option
         "branch.local_next.merge" does not match any remote branch fetched.
No changes.

So this means that branch.local_next.merge should be set to origin/next? Let's have a look at the default in .git/config:

[remote "origin"]
        url = git://git.kernel.org/pub/scm/git/git.git
        fetch = refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

But according to the warning above, branch.master.merge should have been set to refs/remotes/origin/master, not refs/heads/master, right? Otherwise does this mean that master will merge itself into itself?

This is where my own git experience stops as I don't understand the above for real. So let's see the doc:

|branch.<name>.merge::
|        When in branch <name>, it tells `git fetch` the default refspec to
|        be marked for merging in FETCH_HEAD. The value has exactly to match
|        a remote part of one of the refspecs which are fetched from the remote
|        given by "branch.<name>.remote".
|        The merge information is used by `git pull` (which at first calls
|        `git fetch`) to lookup the default branch for merging. Without
|        this option, `git pull` defaults to merge the first refspec fetched.
|        Specify multiple values to get an octopus merge.

Hmmmmmmm... Even after reading this twice I'm still not sure what it really means. But as I said at the top I'm an idiot.

Nicolas