Re: [PATCH] Expand explanation of the use of + in git push refspecs.

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 20, 2009, 05:04 UTC
Message-ID: <7viqn5k8c4.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20090219180258.2C7983360A6@rincewind>

Marc Branchaud <marcnarc@xiplink.com> writes:

Show 18 quoted lines

> Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
> ---
>  Documentation/git-push.txt |   40 ++++++++++++++++++++++++++++++++--------
>  1 files changed, 32 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index 7d1eced..4cb13a1 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -50,20 +50,21 @@ updated.
>  +
>  The object referenced by <src> is used to fast forward the ref <dst>
>  on the remote side. If the optional leading plus `{plus}` is used, the
> -remote ref is updated even if it does not result in a fast forward
> -update.
> +remote ref is *overwritten* with the local ref.  (The use of `{plus}`
> +is recommended only for private, unshared repositories.)  See EXAMPLES
> +below for details.

I am of two minds with this. The understanding of the concept of fast-forwardness is necessary not just to understand push but also to understand merge, and if glossary is missing the definition, we should add one there. What exactly happens when the <dst> is updated is the same regardless of ff or non-ff in that the old 40 hexdecimal object name is gone and replaced with the new one, and it does not feel right to say "if ff, we update if non-ff you can force to overwrite." Either way, you overwrite and there is no trace of the old one. So we would want to say something like:

    The name of the object referenced by <src> is used to update the ref
    <dst> on the remote side, but by default this is only allowed if the
    update is fast-forward.  By having the optional leading plus, you can
    tell git to update the ref <dst> even when the update is not a
    fast-forward.

Show 12 quoted lines

> -The special refspec `:` (or `+:` to allow non-fast forward updates)
> -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).
> +The special refspec `:` (or `{plus}:` to allow overwriting) 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).

I think {plus} change is a good one, but rewording non-ff to overwrite is not.

Please don't wrap a full paragraph, only to change a few sentences. AsciiDoc wraps lines for output just fine; it took me a few extra minutes to make sure there is no other changes.