Re: [PATCH 1/4] Documentation: explain push.default option a bit more

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

Jeff King <peff@peff.net> writes:

> On Fri, Apr 20, 2012 at 04:59:01PM +0200, Matthieu Moy wrote:
>
>> The previous documentation was explaining _what_ the options were doing,
>> but were of little help explaining _why_ a user should set his default to
>> either of the options.
>
> I think your explanations are a definite improvement.

<aol>Me too</aol>

Except for this part.

>  * `current` - push the current branch to a branch of the same name.
> +  This option allows publishing a branch to a remote repository using
> +  the same naming convention locally and remotely, in a more
> +  conservative and safer way than `matching`.

I am not sure if "in a more conservative and safer way than `matching`"
is a good thing to say here.  It sounds as if you are saying "you push
only one, so even if it does what you did not intend to do, you inflict
damage to at most one branch" and without mentioning the downside of
"you push only one, so you need to checkout and push out all the
branches one by one that you care about".

The workflow 'current', 'upstream' and 'simple' are suitable for is
fundamentally different from what 'matching' aims to support.

The former three are for people who want: "I've completed this single
branch, the one I have had in my working tree and have been working on
for all this time. I'll push *that* single branch out. All the other
branches do not participate in this push".

The 'matching' is for people who want: "I've worked on the set of
branches I want to publish until they are _all_ ready.  And now they
are.  Publish all of them with a single connection, atomically, in one
go."

Your text that compares between 'current' and 'matching' does not make
it clear that point.  In a workflow for which 'current' is suitable,
'matching' is not even "a more aggressive and riskier" alternative.  The
text does not make the reader aware of that, and will invite "current is
a more cumbersome and tedious alternative if you want to push out all
than matching", which is a faulty conclusion coming from the same
confusion.

Perhaps make this part a separate paragraph so that it stands out a bit
more, like this,

    * `current` - push the current branch to a branch of the same name.
    +
    The `current` and `upstream` modes are for those who want to
    push out a single branch after finishing work, even when the other
    branches are not yet ready to be pushed out.

and update the description for `matching` to explain why it is suited
for what we claim that it is suited for, like so:

    * `matching` - push all branches having the same name in both ends.
      This is for those who prepare all the branches into a publishable
      shape and push them out atomically, and suitable when pushing to a
      non-shared repository. It is not appropriate to use when pushing into
      a repository shared by multiple users, since locally stalled branches
      will attempt a non-fast forward push if other users updated the branch
      remotely.
    +
    This is the default.