Junio C Hamano <gitster@xxxxxxxxx> writes:
> Anders Melchiorsen <mail@xxxxxxxxxxxxxxxx> 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.
Right, that was poor wording. When I said "special case", I meant it
as "rare use case".
>> 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).
Oh, I did (obviously) not realize that you can use HEAD in that way,
and actually I cannot read that from the quoted paragraph even now
that I know about it.
It seems to me that HEAD is a special-special case, and that it is not
even mentioned in the current documentation. With my current
understanding, I would say that HEAD can work both as a "branch name"
(that discovers its own name automatically) and as an "arbitrary
SHA-1" (with a detached head).
>> --- 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.
I find those paragraphs hard to read. The shorter sentences and lack
of parentheses in my patch series was more to my taste. I actually
think that the examples, like explaining master~4, detracts from the
main topic and makes it harder to find the information.
>> @@ -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'.
Right.
Cheers,
Anders.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
