[PATCH] Amend git-push refspec documentation

[PATCH] Amend git-push refspec documentation

[Sam Vilain]

These paragraphs are a little confusing.  Also, make it clearer when
you have to specify the full name for <dst>

Signed-off-by: Sam Vilain <sam.vilain@catalyst.net.nz>
---
 Documentation/git-push.txt |   22 ++++++++++++----------
 1 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 3128170..b3d164e 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -35,14 +35,14 @@ OPTIONS
 	by the source ref, followed by a colon `:`, followed by
 	the destination ref.
 +
-The <src> side can be an
-arbitrary "SHA1 expression" that can be used as an
-argument to `git-cat-file -t`.  E.g. `master~4` (push
-four parents before the current master head).
+The <src> side represents the source branch (or arbitrary
+"SHA1 expression"; see linkgit:git-rev-parse[1]) 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>.  If
-the optional plus `+` is used, the remote ref is updated
+to fast forward the remote ref that matches <dst> (or, if no <dst> was
+specified, the same ref that <src> referred to locally).  If
+the optional leading plus `+` is used, the remote ref is updated
 even if it does not result in a fast forward update.
 +
 Note: If no explicit refspec is found, (that is neither
@@ -165,7 +165,8 @@ git push origin master::
 	Find a ref that matches `master` in the source repository
 	(most likely, it would find `refs/heads/master`), and update
 	the same ref (e.g. `refs/heads/master`) in `origin` repository
-	with it.
+	with it.  If `master` did not exist remotely, it would be
+	created.
 
 git push origin :experimental::
 	Find a ref that matches `experimental` in the `origin` repository
@@ -179,9 +180,10 @@ git push origin master:satellite/master::
 
 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.
+	by copying the current `master` branch.  This form is only
+	needed to create a new branch in the remote repository when
+	the local name and the remote name are different; otherwise,
+	the branch name on its own will work.
 
 Author
 ------
-- 
1.5.5.1.50.g1d36.dirty

Re: [PATCH] Amend git-push refspec documentation

[Junio C Hamano]

Sam Vilain <sam.vilain@catalyst.net.nz> writes:

> These paragraphs are a little confusing.  Also, make it clearer when
> you have to specify the full name for <dst>
>
> Signed-off-by: Sam Vilain <sam.vilain@catalyst.net.nz>
> ---
>  Documentation/git-push.txt |   22 ++++++++++++----------
>  1 files changed, 12 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 3128170..b3d164e 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -35,14 +35,14 @@ OPTIONS
>  	by the source ref, followed by a colon `:`, followed by
>  	the destination ref.
>  +
> -The <src> side can be an
> -arbitrary "SHA1 expression" that can be used as an
> -argument to `git-cat-file -t`.  E.g. `master~4` (push
> -four parents before the current master head).
> +The <src> side represents the source branch (or arbitrary
> +"SHA1 expression"; see linkgit:git-rev-parse[1]) that you want to
> +push.  The <dst> side represents the destination location.
>  +

Hmm.  We lost an example but refer to a more authoritative information,
which is probably Ok.

>  The local ref that matches <src> is used
> -to fast forward the remote ref that matches <dst>.  If
> -the optional plus `+` is used, the remote ref is updated
> +to fast forward the remote ref that matches <dst> (or, if no <dst> was
> +specified, the same ref that <src> referred to locally).  If
> +the optional leading plus `+` is used, the remote ref is updated
>  even if it does not result in a fast forward update.
>  +

That's an improvement.

> @@ -179,9 +180,10 @@ git push origin master:satellite/master::
>  
>  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.
> +	by copying the current `master` branch.  This form is only
> +	needed to create a new branch in the remote repository when
> +	the local name and the remote name are different; otherwise,
> +	the branch name on its own will work.

Note that writing "refs/tags/xprm" instead would allow you to create a
lightweight tag over there.

Re: [PATCH] Amend git-push refspec documentation

[Sam Vilain]

Junio C Hamano wrote:
>> -The <src> side can be an
>> -arbitrary "SHA1 expression" that can be used as an
>> -argument to `git-cat-file -t`.  E.g. `master~4` (push
>> -four parents before the current master head).
>> +The <src> side represents the source branch (or arbitrary
>> +"SHA1 expression"; see linkgit:git-rev-parse[1]) that you want to
>> +push.  The <dst> side represents the destination location.
>>  +
> 
> Hmm.  We lost an example but refer to a more authoritative information,
> which is probably Ok.

Well, the example I think was quite confusing to people who have never
seen `master~4` before.

>> @@ -179,9 +180,10 @@ git push origin master:satellite/master::
>>  
>>  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.
>> +	by copying the current `master` branch.  This form is only
>> +	needed to create a new branch in the remote repository when
>> +	the local name and the remote name are different; otherwise,
>> +	the branch name on its own will work.
> 
> Note that writing "refs/tags/xprm" instead would allow you to create a
> lightweight tag over there.

True.  You could probably replace 'branch' with 'ref' in the two places
it occurs in the last sentence to encompass that meaning, too.

Cheers,
Sam.