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

[Junio C Hamano <gitster@pobox.com>]

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