Many users get confused when `git push origin master:foo` works

when foo already exists on the remote repository but are confused

when foo doesn't exist as a branch and this form does not create

the branch foo.
This new example highlights the trick of including refs/heads/

in front of the desired branch name to create a branch.
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

---

 Documentation/git-push.txt |    6 ++++++

 1 files changed, 6 insertions(+), 0 deletions(-)
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt

index 0dd9caf..7b8e075 100644

--- a/Documentation/git-push.txt

+++ b/Documentation/git-push.txt

@@ -117,6 +117,12 @@ git push origin master:satellite/master::

 	the ref that matches `satellite/master` (most likely, it would

 	be `refs/remotes/satellite/master`) in `origin` repository with it.
+git push origin master:refs/heads/experimental::

+	Create the branch `experimental` in the `origin` repository

+	by copying the current `master` branch.  This form is usually

+	needed to create a new branch in the remote repository as

+	there is no `experimental` branch to match.

+

 Author

 ------

 Written by Junio C Hamano <junkio@cox.net>, later rewritten in C

--

1.5.3.1.840.g0fedbc

-

El 6/9/2007, a las 6:44, Shawn O. Pearce escribi

Indeed, but a even better approach might be to expand the error message

with a sugestion on how to create a branch.
Kristian
-

Hmm, what _does_ it do in that case...?
-Miles
--

If you can't beat them, arrange to have them beaten.  [George Carlin]

-

error: dst refspec experimental does not match any existing ref on the remote and does not start with refs/.
--

Shawn.

-

Hmm, I'm assuming people don't want to default to just creating a new

remote ref ('cause it might be too easy to muck up a remote archive

that way), but it seems like it would be nice to have a "prettier" way

to create a remote ref than explicitly giving the whole ref path on

the remote side.
Maybe I"m weird, but I tend to think of the refs/... syntax as being

for "only if you're doing something funny" cases.
I'm thinking of something like:
  ... create new local branch "zoink" ...

  git push --create origin zoink
-Miles
--

Do not taunt Happy Fun Ball.

-

The "refs/" syntax is there as the lowest level that is

universally usable to create and any ref.  It can be used to

push to branches, tags, or even remotes (aka "simulated fetch in

reverse").
It is just nobody felt strong enough reason to sugarcoat the

normalized syntax with something like:
	git push --create remote foo v1.2.0
You can be a hero by updating git-push to take such, and make it

interpret as if the user passed the normalized syntax which is:
	git push remote foo:refs/heads/foo v1.2.0:refs/tags/v1.2.0
-

Actually
 	git push remote foo v1.2.0
already expands that way today, without the --create logic you are

talking about introducing.  Its part of the DWIM-ery of today's

git-push.  Yes, really, you don't even need to say "tag v1.2.0"

to create the tag v1.2.0 on the remote side.
Where people run into problems is when they want to rename the branch

during push and create the new name on the remote.  Our remote-side

matching logic works sometimes (when there is a matching name on

the remote side) and not others (when there is not a matching name).

That can be very confusing.
E.g. users want to be able to do something such as:
	git push remote experimental:pu
and just have refs/heads/pu be created because experimental is

also a branch in the local repository and pu does not exist on the

remote side.  There is of course the workaround of:
	git branch -m experimental pu

	git push remote pu

	git branch -m pu experimental
but that's really really annoying to have to use to make git-push

DWIM.
Users expect this to work because it does if refs/heads/pu already

exists on the remote.  For many workflows it is also more common

for branches to exist on the remote and just need updating than

it is for for them to be created new; consequently users see the

"rename during push" magic Just Work(tm).  Then when it fails

during remote side branch creation Git is instantly the Goddamn

Idotic Truckload of s**t.  :-\
--

Shawn.

-

That's quite "yeah, sometimes it may be the case, but...".
You may want to also do:
	git push remote experimental:v0.0.1-rc0
to give preview tag without really bothering to create an

annotated tag.
-

Couldn't we just use an initial + to indicate this as well?
I would imagine an exchange like this:
    $ git push remote foo

    git: No branch 'foo' exists in the remote server, to create it use:
	git push remote +foo
But regardless of the syntax, it would be nice if the error message

were explicit about how to achieve the goal the user wants. It's just

that forcing the user to say "foo:refs/heads/foo" seems a way to force

the user to get plumbing grime on their clean hands.
-Carl

Unfortunately, no, because + has already been taken to mean

something completely different.

-