From: Anders Melchiorsen <mail@cup•kalibalik.dk>
To: Junio C Hamano <gitster@pobox•com>
Cc: git@vger•kernel.org
Subject: Re: [PATCH 3/7] Documentation: rework SHA1 description in git push
Date: Sun, 02 Nov 2008 21:13:21 +0100 [thread overview]
Message-ID: <873ai9opi6.fsf@cup.kalibalik.dk> (raw)
In-Reply-To: <7v1vxxba2c.fsf@gitster.siamese.dyndns.org> (Junio C. Hamano's message of "Thu\, 30 Oct 2008 22\:36\:11 -0700")
Junio C Hamano <gitster@pobox•com> writes:
> 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.
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.
next prev parent reply other threads:[~2008-11-02 20:14 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-10-29 20:25 Some updates to refspec documentation Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 1/7] Documentation: do not use regexp in refspec descriptions Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 2/7] Documentation: git push repository can also be a remote Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 3/7] Documentation: rework SHA1 description in git push Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 4/7] Documentation: remove a redundant elaboration Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 5/7] Documentation: elaborate on pushing tags Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 6/7] Documentation: mention branches rather than heads Anders Melchiorsen
2008-10-29 20:25 ` [PATCH 7/7] Documentation: avoid using undefined parameters Anders Melchiorsen
2008-10-29 20:40 ` [PATCH 5/7] Documentation: elaborate on pushing tags Daniel Barkalow
2008-10-31 5:36 ` [PATCH 3/7] Documentation: rework SHA1 description in git push Junio C Hamano
2008-11-02 20:13 ` Anders Melchiorsen [this message]
2008-10-31 5:35 ` [PATCH 1/7] Documentation: do not use regexp in refspec descriptions Junio C Hamano
2008-11-02 17:08 ` Anders Melchiorsen
2008-10-29 20:41 ` Some updates to refspec documentation Anders Melchiorsen
2008-10-29 20:44 ` Anders Melchiorsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=873ai9opi6.fsf@cup.kalibalik.dk \
--to=mail@cup$(echo .)kalibalik.dk \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox