git-push: creating branch on remote, refspec format

http://www.kernel.org/pub/software/scm/git/docs/git-push.html reads:

| git push origin master:refs/heads/experimental
| 
|   Create the branch experimental in the origin repository by copying the 
|   current master branch. This form is only needed to create a new branch or 
|   tag in the remote repository when the local name and the remote name are 
|   different; otherwise, the ref name on its own will work.

It appears to me that the ref name on its own will also work to create a new branch, at least with local repositories:

$ (mkdir a && cd a && git init)
Initialized empty Git repository in /tmp/a/.git/
$ mkdir b && cd b && git init
Initialized empty Git repository in /tmp/b/.git/
$ pwd
/tmp/b
$ touch x && git add x && git commit 
[master (root-commit)]: created 87a90f5: "NA"
 0 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 x

Now the push from '/tmp/b' to '/tmp/a':

$ git push /tmp/a master:foo
Counting objects: 3, done.
Writing objects: 100% (3/3), 209 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (3/3), done.
To /tmp/a
 * [new branch]      master -> foo

Am I missing something?

Lasse Kliemann venit, vidit, dixit 26.02.2009 13:00:

You're using the very same form as the doc. "This form" in the doc refers to "repo refspec", i.e. something like "a b:c", which is what you use. The "refs/heads/" part is just there to disambiguate between possible different matches on the remote side (refs/heads/foo, refs/tags/foo, refs/remotes/bar/foo, ...).

Michael

Actually, it used to be that case that git would complain unless "foo" was properly qualified; this was fixed in f8aae12 (push: allow unqualified dest refspecs to DWIM, 2008-04-23), which is in v1.5.5.2.

The doc in question was added around v1.5.3. So I think it is simply that it was never updated to match the new behavior. That paragraph could probably even just be deleted, since there is no syntactic difference between pushing to an existing branch and creating a new branch (alternatively, it can say explicitly that creating a new branch is the same as pushing to one).

-Peff