Re: [PATCH] doc: attempt to clarify a blurry sentence.

[Junio C Hamano <gitster@pobox.com>]

"Lars Berntzon via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
> index a953c7c38790..bbb30c52395e 100644
> --- a/Documentation/git-push.txt
> +++ b/Documentation/git-push.txt
> @@ -66,10 +66,10 @@ it can be any arbitrary "SHA-1 expression", such as `master~4` or
>  The <dst> tells which ref on the remote side is updated with this
>  push. Arbitrary expressions cannot be used here, an actual ref must
>  be named.
> -If `git push [<repository>]` without any `<refspec>` argument is set to
> -update some ref at the destination with `<src>` with
> -`remote.<repository>.push` configuration variable, `:<dst>` part can
> -be omitted--such a push will update a ref that `<src>` normally updates
> +If `git push [<repository>]` without any `<refspec>` argument then
> +git will update the remote ref as defined by `remote.<repository>.push` configuration
> +and it will be updated from HEAD.
> +`:<dst>` part can be omitted--such a push will update a ref that `<src>` normally updates

Hmph, "If X then Git will do Y" expects X to be a full sentence with
subject and verb, but I do not see any verb in 

    `git push [<repository>]` without any `<refspec>` argument

in the rewritten version.

More importantly, the updated description is wrong.  The original
may be hard to follow, but what it is trying to explain is the
following.

Imagine that you have configured

	[remote "origin"]
		push = refs/heads/*:refs/remotes/satellite/*

Imagine further that you have a local branch 'next' and you want to
push it out to the "origin".  You also have other local branches
like 'master' and 'maint', but you do not wish to push them out
right now.

Under such a scenario, if you were to type

    $ git push origin

(i.e. "`git push [<repository>]` without `<refspec>` argument"),
such a command is set to update `refs/remotes/satellite/next`
(i.e. "some ref") at the "origin" (i.e. "the destination") with
`next` (i.e. "with <src>") via the remote.origin.push configuration
variable.  So this scenario satisfies the precondition of the
description we are discussing.

In such a case, you do not have to fully spell out

    $ git push origin next:refs/remotes/satellite/next

in order to push your 'next' branch (which may not be the current
branch) from the command line to its usual/configured destination.

Instead, you can omit ":<dst>", i.e.

    $ git push origin next

and such a push will update the remote ref that would be normally
updated by the local ref named on the command line, i.e. the remote
'refs/remotes/satellite/next' will be updated with your local
'refs/heads/next'.  But your 'master' and 'maint' will not be pushed
to their usual/configured destinations with such a push.

Again, the original may hard to read and it can use some rewriting
to make it easier to read.  Thanks for trying to help by attempting,
and another try with the above information in mind is greatly
appreciated.