Re: [PATCH] doc: pull: improve rebase=false documentation

[Linus Arver <linusa@google.com>]

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

> Dragan Simic <dsimic@manjaro.org> writes:
>
>> Mention in the documentation that --rebase defaults to false.
>
> I am not quite sure if this is an improvement, though.
>
> It is true that, if you do not have any of your own funny
> configuration, your "git pull" will *not* rebase.  
>
> But that is "if you do not give the --rebase option, you do not
> trigger the rebase action".  Which is quite natural, but it is
> different from what you wrote above, isn't it?
>
> When people say "the default for `--rebase` is false", they mean
> this:
>
>     I can say "git pull --rebase=<kind>" to specify how my current
>     branch is rebased on top of the upstream.  But if I do not
>     specify the <kind>, i.e. "git pull --rebase", the command will
>     act as if I gave 'false' as the <kind>.
>
> At least, I would think that is what the word "default" means.
>
> And I would be surprised if the "default" in that sense is 'false';
> isn't the default <kind> 'true' --- meaning "perform the plain
> vanilla 'git rebase'", unless you explicitly asked for 'merges',
> 'interactive' or 'false'?
>
> After the context of the hunk your patch touches, there is a
> description on `pull.rebase`.  Down there, if you do not set
> `pull.rebase` or `branch.<name>.rebase` for the current branch at
> all, the system acts as if you had `false` for these variables.  In
> other words, the default for these variables is `false`, meaning "do
> not rebase, just merge".  But the default option argument for the
> `--rebase` option given without argument would not be `false`, I
> would think.

I think there are two reasonable interpretations of the word "default"
here.

(1) "git pull": This is equivalent to "git pull --rebase=false". So one
could say that "git pull" defaults to "--rebase=false".

(2) "git pull --rebase": This is equivalent to "git pull --rebase=true".
So one could say that the "--rebase" flag (when it is used as "--rebase"
without the "=..." part) defaults to "--rebase=true".

I assume Dragan was thinking of only the meaning in (1). The alternate
meaning of (2) which you brought up makes sense too.

I think both flavors of "default" are reasonable interpretations because
most (if not all) Git users will start out with (1) in mind as they get
familiar with how "git pull" works without any flags (i.e., the
"default" git-pull behavior). Eventually they'll learn about (2) and
realize how the <kind> defaults to "true" with the "--rebase" flag.

Aside: interestingly, there appears to be a "--no-rebase" option that
means "--rebase=false" (see cd67e4d46b (Teach 'git pull' about --rebase,
2007-11-28)):

       --no-rebase
           This is shorthand for --rebase=false.

>> Signed-off-by: Dragan Simic <dsimic@manjaro.org>
>> ---
>>  Documentation/git-pull.txt | 3 ++-
>>  1 file changed, 2 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
>> index 0e14f8b5b2..d28790388e 100644
>> --- a/Documentation/git-pull.txt
>> +++ b/Documentation/git-pull.txt
>> @@ -116,7 +116,8 @@ When set to `merges`, rebase using `git rebase --rebase-merges` so that
>>  the local merge commits are included in the rebase (see
>>  linkgit:git-rebase[1] for details).
>>  +
>> -When false, merge the upstream branch into the current branch.
>> +When false, merge the upstream branch into the current branch. This is
>> +the default.
>>  +
>>  When `interactive`, enable the interactive mode of rebase.
>>  +

For reference here is a more complete view of the docs for this flag:

    -r::
    --rebase[=false|true|merges|interactive]::
        When true, rebase the current branch on top of the upstream
        branch after fetching. If there is a remote-tracking branch
        corresponding to the upstream branch and the upstream branch
        was rebased since last fetched, the rebase uses that information
        to avoid rebasing non-local changes.
    +
    When set to `merges`, rebase using `git rebase --rebase-merges` so that
    the local merge commits are included in the rebase (see
    linkgit:git-rebase[1] for details).
    +
    When false, merge the upstream branch into the current branch.
    +
    When `interactive`, enable the interactive mode of rebase.
    +
    See `pull.rebase`, `branch.<name>.rebase` and `branch.autoSetupRebase` in
    linkgit:git-config[1] if you want to make `git pull` always use
    `--rebase` instead of merging.

How about adding something like this instead as the very first paragraph
for this flag?

    Supplying "--rebase" defaults to "--rebase=true". Running git-pull
    without arguments implies "--rebase=false", unless relevant
    configuration variables have been set otherwise.

This way, we can discuss what "true" and "false" mean first to get these
two flavors of "defaults" sorted out (perhaps also mentioning
--no-rebase while we're at it). Then we can discuss the other <kind>
values like "merges" and "interactive".