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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 20, 2012, 21:28 UTC
Message-ID: <xmqq62cum6tf.fsf@junio.mtv.corp.google.com>
In-Reply-To: <20120420201357.GA13103@sigill.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 7 quoted lines

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