Some updates to refspec documentation

I have skimmed the git-push manpage many times over a period of
several months, without fully understanding it. Today I sat down and
figured it out. It took some experiments and a little reading of the
source.

Here I offer some updates to the refspec documentation, so that others
can hopefully learn it faster than I did. As I expect some changes to
be more controversial than others, I have split it up in several small
parts. Feel free to squash.

There is a risk that I have changed some things to be wrong. I wanted
to make this update while I was still a frustrated newbie.



Anders

The refspec format description was a mix of regexp and BNF, making it
very difficult to read.

The syntax is now easier to read, though wrong: all parts of the
refspec are actually optional.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt         |    2 +-
 Documentation/pull-fetch-param.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 6150b1b..df99c0b 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -32,7 +32,7 @@ OPTIONS
 
 <refspec>...::
 	The canonical format of a <refspec> parameter is
-	`+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
+	`[+]<src>:<dst>`; that is, an optional plus `{plus}`, followed
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index ebdd948..0ff1700 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt

@@ -6,7 +6,7 @@
 
 <refspec>::
 	The canonical format of a <refspec> parameter is
-	`+?<src>:<dst>`; that is, an optional plus `{plus}`, followed
+	`[+]<src>:<dst>`; that is, an optional plus `{plus}`, followed
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +

-- 
1.6.0.2.514.g23abd3

Most of the git push page talks about branches, so make it consistent
also in this paragraph.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 52035db..4e339c7 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -53,8 +53,8 @@ Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.
 +
 The special refspec `:` (or `+:` to allow non-fast forward updates)
-directs git to push "matching" heads: for every head that exists on
-the local side, the remote side is updated if a head of the same name
+directs git to push "matching" branches: for every branch that exists on
+the local side, the remote side is updated if a branch of the same name
 already exists on the remote side.  This is the default operation mode
 if no explicit refspec is found (that is neither on the command line
 nor in any Push line of the corresponding remotes file---see below).

-- 
1.6.0.2.514.g23abd3

Get rid of a double pair of parentheses. The arbitrary SHA1 is a
special case, so it can be postponed a bit.

Also mention HEAD, which is possibly the most useful SHA1 in this
situation.

Mention that a SHA1 cannot be automatically matched to a <dst>.

Add HEAD as an example of an arbitrary SHA1.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |   12 +++++++++---
 1 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 02c7dae..fb9fb97 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -38,9 +38,7 @@ OPTIONS
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +
-The <src> side represents the source branch (or arbitrary
-"SHA1 expression", such as `master~4` (four parents before the
-tip of `master` branch); see linkgit:git-rev-parse[1]) that you
+The <src> side represents the source branch that you
 want to push.  The <dst> side represents the destination location.
 +
 The local ref that matches <src> is used

@@ -63,6 +61,10 @@ the local side, the remote side is updated if a head of the same name
 already exists on the remote side.  This is the default operation mode
 if no explicit refspec is found (that is neither on the command line
 nor in any Push line of the corresponding remotes file---see below).
++
+The <src> can be an arbitrary "SHA1 expression", such as `HEAD`
+or `master~4` (see linkgit:git-rev-parse[1]). In this case, a
+<dst> location has to be named.
 
 --all::
 	Instead of naming each ref to push, specifies that all

@@ -193,6 +195,10 @@ git push origin master::
 	with it.  If `master` did not exist remotely, it would be
 	created.
 
+git push origin HEAD:master::
+	Push the current head to the remote ref matching `master` in
+	the `origin` repository.
+
 git push origin :experimental::
 	Find a ref that matches `experimental` in the `origin` repository
 	(e.g. `refs/heads/experimental`), and delete it.

-- 
1.6.0.2.514.g23abd3

The comment in parentheses is wrong, as one has to leave out both the
colon and <dst>. This situation is covered by the section a few lines
down:

  A parameter <ref> without a colon pushes the <ref> from the source
  repository to the destination repository under the same name.

So, just remove the parentheses.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index fb9fb97..9788d49 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -42,8 +42,7 @@ The <src> side represents the source branch that you
 want to push.  The <dst> side represents the destination location.
 +
 The local ref that matches <src> is used
-to fast forward the remote ref that matches <dst> (or, if no <dst> was
-specified, the same ref that <src> referred to locally).  If
+to fast forward the remote ref that matches <dst>.  If
 the optional leading plus `+` is used, the remote ref is updated
 even if it does not result in a fast forward update.
 +

-- 
1.6.0.2.514.g23abd3

The <ref> parameter has not been introduced, so rewrite to
avoid it.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 4e339c7..e848ff9 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -46,8 +46,8 @@ to fast forward the remote ref that matches <dst>.  If
 the optional leading plus `+` is used, the remote ref is updated
 even if it does not result in a fast forward update.
 +
-A parameter <ref> without a colon pushes the <ref> from the source
-repository to the destination repository under the same name.
+A lonely <src> parameter (without a colon and a destination) pushes
+the <src> to the same name in the destination repository.
 +
 Pushing an empty <src> allows you to delete the <dst> ref from
 the remote repository.

-- 
1.6.0.2.514.g23abd3

This is copied from pull-fetch-param.txt and helps the reader
to not get stuck in the URL section.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index df99c0b..02c7dae 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -28,7 +28,9 @@ OPTIONS
 -------
 <repository>::
 	The "remote" repository that is destination of a push
-	operation.  See the section <<URLS,GIT URLS>> below.
+	operation.  This parameter can be either a URL
+	(see the section <<URLS,GIT URLS>> below) or the name
+	of a remote (see the section <<REMOTES,REMOTES>> below).
 
 <refspec>...::
 	The canonical format of a <refspec> parameter is

-- 
1.6.0.2.514.g23abd3

Make the description of pushing tags easier to read, but move the
shorthand notation towards the end of the description. This gives
a better flow.

Signed-off-by: Anders Melchiorsen <redacted>
---
 Documentation/git-push.txt |    8 +++++---
 1 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 9788d49..52035db 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt

@@ -38,7 +38,7 @@ OPTIONS
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +
-The <src> side represents the source branch that you
+The <src> side represents the source branch or tag that you
 want to push.  The <dst> side represents the destination location.
 +
 The local ref that matches <src> is used

@@ -46,8 +46,6 @@ to fast forward the remote ref that matches <dst>.  If
 the optional leading plus `+` is used, the remote ref is updated
 even if it does not result in a fast forward update.
 +
-`tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`.
-+
 A parameter <ref> without a colon pushes the <ref> from the source
 repository to the destination repository under the same name.
 +

@@ -64,6 +62,10 @@ nor in any Push line of the corresponding remotes file---see below).
 The <src> can be an arbitrary "SHA1 expression", such as `HEAD`
 or `master~4` (see linkgit:git-rev-parse[1]). In this case, a
 <dst> location has to be named.
++
+When pushing tags, `tag <tag>` can be used as a shorthand for
+`refs/tags/<tag>:refs/tags/<tag>`. This should be specified as
+two arguments (that is, without quotes in the shell).
 
 --all::
 	Instead of naming each ref to push, specifies that all

-- 
1.6.0.2.514.g23abd3

On Wed, 29 Oct 2008, Anders Melchiorsen wrote:

I think this should be "When pushing a tag, ...", to avoid confusion with 
"--tags", which pushes (all) tags and doesn't need the "tag <tag>" 
arguments.

	-Daniel
*This .sig left intentionally blank*

Anders Melchiorsen [off-list ref] writes:

The refspec format description was a mix of regexp and BNF, making it
very difficult to read.

The syntax is now easier to read, though wrong: all parts of the
refspec are actually optional.

It probably is easier to read, but strictly speaking it is not wrong.  The
two parts, <src> and <dst>, _always_ exist, even though either or both of
them can be an empty string.

I am wondering if it would be clearer and easier to understand if we just
said:

  	The canonical format of a <refspec> parameter is
	an optional plus `{plus}`, followed by the source ref,
        followed by a colon `:`, followed by the destination ref.
	Find various forms of refspecs in examples section.

Anders Melchiorsen [off-list ref] writes:

Get rid of a double pair of parentheses. The arbitrary SHA1 is a
special case, so it can be postponed a bit.

Hmmm...

Strictly speaking, arbitrary SHA-1 is the general case, and branch name is
a special case of it, but in practice, branch name is the most frequently
used form, and that is why it has the short-hand convention that allows it
to to be pushed to the same name.  I agree with the outcome of this patch
(except for one point I'll mention shortly) because I think it is a good
idea to talk about most frequently used form first, not because "branch"
is the general case.  IOW, the proposed commit log message is wrong.

Also mention HEAD, which is possibly the most useful SHA1 in this
situation.

HEAD is indeed useful, but it falls into the special case of "branch
name", not "arbitrary SHA-1 expression".  This distinction is important
because you can push "HEAD" without colon and it will act as if you said
master:master (or whatever branch you are currently on).  This is already
described in the existing doc:

    The local ref that matches <src> is used
    to fast forward the remote ref that matches <dst> (or, if no <dst> was
    specified, the same ref that <src> referred to locally).

but I agree that it is unnecessarily hard to understand, because the
document tries to describe the general case first and then relies on the
user to understand that "ref <src> referred to locally" means "branch
name".  We should make this part more explicit.

With that in mind, I have two paragraphs to replace the parts your patch
touches as a counterproposal.

The <src> is often the name of the branch you would want to push, but it
can be any arbitrary "SHA-1 expression", such as `master~4` (four parents
before the tip of `master` branch -- see linkgit:git-rev-parse[1]), or
`HEAD` (the tip of the current branch).  The <dst> tells which ref on the
remote side is updated with this push.

The object referenced by <src> is used to fast forward the ref <dst> on
the remote side.  You can omit <dst> to update the same ref on the remote
side as <src> (<src> is often the name of a branch you push, and often you
push to the same branch on the remote side; `git push HEAD` is a handy way
to push only the current branch to the remote side under the same name).
If the optional leading plus `{plus}` is used, the remote ref is updated
even if it does not result in a fast forward update.

Additional example is good, but you would want to tell readers that this
would be useful when your current branch is _not_ 'master'.