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

Anders Melchiorsen <mail@cup.kalibalik.dk> writes:

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.

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.

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.

Additional example is good, but you would want to tell readers that this would be useful when your current branch is _not_ 'master'.