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

Junio C Hamano [off-list ref] writes:

Anders Melchiorsen [off-list ref] writes:

quoted

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

quoted

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

quoted

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

quoted

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