patch, 7 partsDocumentation: do not use regexp in refspec descriptions

I have skimmed the git-push manpage many times over a period of several months, without fully understanding it. Today I sat down and figured it out. It took some experiments and a little reading of the source.

Here I offer some updates to the refspec documentation, so that others can hopefully learn it faster than I did. As I expect some changes to be more controversial than others, I have split it up in several small parts. Feel free to squash.

There is a risk that I have changed some things to be wrong. I wanted to make this update while I was still a frustrated newbie.

Anders

The refspec format description was a mix of regexp and BNF, making it very difficult to read.

The syntax is now easier to read, though wrong: all parts of the refspec are actually optional.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt         |    2 +-
 Documentation/pull-fetch-param.txt |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

This is copied from pull-fetch-param.txt and helps the reader to not get stuck in the URL section.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 +++-
 1 files changed, 3 insertions(+), 1 deletions(-)

Get rid of a double pair of parentheses. The arbitrary SHA1 is a special case, so it can be postponed a bit.

Also mention HEAD, which is possibly the most useful SHA1 in this situation.

Mention that a SHA1 cannot be automatically matched to a <dst>.

Add HEAD as an example of an arbitrary SHA1.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |   12 +++++++++---
 1 files changed, 9 insertions(+), 3 deletions(-)

The comment in parentheses is wrong, as one has to leave out both the colon and <dst>. This situation is covered by the section a few lines down:

  A parameter <ref> without a colon pushes the <ref> from the source
  repository to the destination repository under the same name.

So, just remove the parentheses.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

Make the description of pushing tags easier to read, but move the shorthand notation towards the end of the description. This gives a better flow.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    8 +++++---
 1 files changed, 5 insertions(+), 3 deletions(-)

Most of the git push page talks about branches, so make it consistent also in this paragraph.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

The <ref> parameter has not been introduced, so rewrite to avoid it.

Signed-off-by: Anders Melchiorsen <mail@cup.kalibalik.dk>
---
 Documentation/git-push.txt |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

On Wed, 29 Oct 2008, Anders Melchiorsen wrote:

I think this should be "When pushing a tag, ...", to avoid confusion with "--tags", which pushes (all) tags and doesn't need the "tag <tag>" arguments.

	-Daniel
*This .sig left intentionally blank*

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

Junio C Hamano <gitster@pobox.com> writes:

Right, that was poor wording. When I said "special case", I meant it as "rare use case".

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

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.

Right.

Cheers, Anders.

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

It probably is easier to read, but strictly speaking it is not wrong. The two parts, <src> and <dst>, _always_ exist, even though either or both of them can be an empty string.

I am wondering if it would be clearer and easier to understand if we just said:

  	The canonical format of a <refspec> parameter is
	an optional plus `{plus}`, followed by the source ref,
        followed by a colon `:`, followed by the destination ref.
	Find various forms of refspecs in examples section.

Junio C Hamano <gitster@pobox.com> writes:

The colon is not required, though the format suggests that it is.

I think that is an improvement. Removing the word "canonical" would be even better, IMHO.

Anders.

During my struggle, I also found a git push usability problem. The refspec ":dst" will delete the remote branch without warning.

While this is indeed documented, you cannot blame somebody for thinking that a left out <src> will default to HEAD, as it does for so many other commands.

In a CVS-like setup, with everybody pushing to master, this could cause havoc.

As the "git push <repository> :<dst>" operation is destructive, I think it should be protected by the -f option.

For the record, I did realize this before trying to push ":master" :-).

Anders.

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

I actually think that <src> defaulting to HEAD would be reasonable, but it is probably less reasonable to change the meaning at this point.

Anders