Some updates to refspec documentation

Some updates to refspec documentation

[Anders Melchiorsen]

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

[PATCH 1/7] Documentation: do not use regexp in refspec descriptions

[Anders Melchiorsen]

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 <mail@cup.kalibalik.dk>
---
 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

[PATCH 2/7] Documentation: git push repository can also be a remote

[Anders Melchiorsen]

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 <mail@cup.kalibalik.dk>
---
 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

[PATCH 3/7] Documentation: rework SHA1 description in git push

[Anders Melchiorsen]

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 <mail@cup.kalibalik.dk>
---
 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

[PATCH 4/7] Documentation: remove a redundant elaboration

[Anders Melchiorsen]

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 <mail@cup.kalibalik.dk>
---
 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

[PATCH 5/7] Documentation: elaborate on pushing tags

[Anders Melchiorsen]

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 <mail@cup.kalibalik.dk>
---
 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

[PATCH 6/7] Documentation: mention branches rather than heads

[Anders Melchiorsen]

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

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 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

[PATCH 7/7] Documentation: avoid using undefined parameters

[Anders Melchiorsen]

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

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 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

Re: [PATCH 5/7] Documentation: elaborate on pushing tags

[Daniel Barkalow]

On Wed, 29 Oct 2008, Anders Melchiorsen wrote:

> 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 <mail@cup.kalibalik.dk>
> ---
>  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).

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*

Re: Some updates to refspec documentation

[Anders Melchiorsen]

During my struggle, I also found a git push usability problem. The
refspec ":dst" will delete the remote branch without warning.

While this is indeed documented, you cannot blame somebody for
thinking that a left out <src> will default to HEAD, as it does for so
many other commands.

In a CVS-like setup, with everybody pushing to master, this could
cause havoc.

As the "git push <repository> :<dst>" operation is destructive, I
think it should be protected by the -f option.

For the record, I did realize this before trying to push ":master" :-).



Anders.

Re: Some updates to refspec documentation

[Anders Melchiorsen]

Anders Melchiorsen <mail@cup.kalibalik.dk> writes:

> While this is indeed documented, you cannot blame somebody for
> thinking that a left out <src> will default to HEAD, as it does for
> so many other commands.

I actually think that <src> defaulting to HEAD would be reasonable,
but it is probably less reasonable to change the meaning at this
point.



Anders

Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions

[Junio C Hamano]

Anders Melchiorsen <mail@cup.kalibalik.dk> 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.

> 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.

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.

Re: [PATCH 3/7] Documentation: rework SHA1 description in git push

[Junio C Hamano]

Anders Melchiorsen <mail@cup.kalibalik.dk> 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.

> 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 <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.

> @@ -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.
> +

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

Re: [PATCH 1/7] Documentation: do not use regexp in refspec descriptions

[Anders Melchiorsen]

Junio C Hamano <gitster@pobox.com> writes:

> Anders Melchiorsen <mail@cup.kalibalik.dk> writes:
>
>> 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.

The colon is not required, though the format suggests that it is.


>>  <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.
>
> 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.

I think that is an improvement. Removing the word "canonical" would be
even better, IMHO.


Anders.

Re: [PATCH 3/7] Documentation: rework SHA1 description in git push

[Anders Melchiorsen]

Junio C Hamano <gitster@pobox.com> writes:

> Anders Melchiorsen <mail@cup.kalibalik.dk> 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.

Right, that was poor wording. When I said "special case", I meant it
as "rare use case".


>> 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).

Oh, I did (obviously) not realize that you can use HEAD in that way,
and actually I cannot read that from the quoted paragraph even now
that I know about it.

It seems to me that HEAD is a special-special case, and that it is not
even mentioned in the current documentation. With my current
understanding, I would say that HEAD can work both as a "branch name"
(that discovers its own name automatically) and as an "arbitrary
SHA-1" (with a detached head).


>> --- 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 <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.

I find those paragraphs hard to read. The shorter sentences and lack
of parentheses in my patch series was more to my taste. I actually
think that the examples, like explaining master~4, detracts from the
main topic and makes it harder to find the information.



>> @@ -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.
>> +
>
> Additional example is good, but you would want to tell readers that this
> would be useful when your current branch is _not_ 'master'.

Right.



Cheers,
Anders.