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

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