Re: [PATCH] Amend git-push refspec documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 22, 2008, 05:48 UTC
Message-ID: <7vk5iq5tj2.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <1208748684-28253-1-git-send-email-sam.vilain@catalyst.net.nz>

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

Show 24 quoted lines

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

Show 8 quoted lines

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

Show 11 quoted lines

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