From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 20 Feb 2009 05:04:11 GMT
Subject: Re: [PATCH] Expand explanation of the use of + in git push refspecs.
Message-ID: <7viqn5k8c4.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20090219180258.2C7983360A6@rincewind>

Marc Branchaud <marcnarc@xiplink.com> writes:

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

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