From: Eric Sunshine <sunshine@sunshineco.com>
Date: Fri, 19 Jul 2013 20:29:20 GMT
Subject: Re: [PATCH v2] pull: require choice between rebase/merge on non-fast-forward pull
Message-ID: <CAPig+cQEtKc+tfDgqVWYL2JtxXc=wvS=P7_O=XJzizz1BN=n4A@mail.gmail.com>
In-Reply-To: <7vy592wmcs.fsf@alter.siamese.dyndns.org>

On Fri, Jul 19, 2013 at 12:22 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
>
>>> +When `git pull` that does not explicitly specify what branch from
>>> +which repository is to be integrated with your history on the
>>> +command line, recent Git will refuse to work until you specify how
>>> +that integration should happen, either with a command line option
>>> +(`--merge` or `--rebase`) or a configuration variable (`pull.rebase`
>>> +or `branch.<name>.rebase`, which is the same as `--merge`
>>> +(`--rebase`) when set to `false` (`true`) respectively.
>>
>> This paragraph-long single sentence may be intimidating. Perhaps some
>> simplification is possible:
>>
>>     As a safety measure, bare `git pull` (without repository or
>>     branch) needs to be told how to integrate pulled changes with
>>     your history; either via `--merge` or `--rebase`.  Also see
>>     configuration variables `pull.rebase` and `branch.<name>.rebase`
>>     in linkgit:git-config[1].
>>
>> I intentionally omitted the true/false explanation of the
>> configuration variables since the user can follow the link and read
>> about them. It also may make sense to drop mention of those variables
>> altogether since they are already described (including link) in the
>> description of --rebase.
>>
>> I also intentionally omitted "recent Git" since it's rather nebulous.
>
> Looks much better than the original.  I would further suggest
> dropping the "As a safety measure, bare " at the beginning.
>
>       `git pull` (without repository or branch on the command line)
>       needs to be told how to integrate the changes with your
>       history via either `--merge` or `--rebase` (see configuration
>       variables `pull.rebase` and `branch.<name>.rebase` in
>       linkgit:git-config[1]).
>
> perhaps?

That works; or without the mentioning the configuration variables at
all (assuming the reader will discover them from reading --rebase
description):

    `git pull` (without repository or branch on the command line)
    needs to be told how to integrate the changes with your history
    via either `--merge` or `--rebase`.

Dropping the parenthetical comment might improve flow slightly:

    Without repository or branch on the command line, `git pull`
    needs to be told how to integrate the changes with your history,
    via either `--merge` or `--rebase`.

With or without mention of the configuration options, either phrasing
seems pretty easy to digest.