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

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

Linus Arver <linusa@google.com> writes:

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

Phrase nit.

	$ git pull origin

does run the command with arguments.  What you mean is "running
git-pull without any --rebase arguments implies --no-rebase", but
that is saying "not giving --rebase=<any> and not giving --rebase
means not rebasing", which makes my head spin.

"--no-rebase" as a command line option does have use to defeat
configured pull.rebase that is not set to "false", and allowing
"pull.rebase" to be set to "false" does have use to defeat settings
for the same variable made by lower-precedence configuration file.
"--rebase=false" does not have any reason to exist, except for
making the repertoire of "--rebase=<kind>" to be complete.

So, I am still not sure if saying "'git pull' (no other arguments
and no configuration) is equivalent to 'git pull --rebase=false'"
adds much value.

If --no-rebase and --rebase=false are explained in terms of why
these options that specify such an unnatural action (after all, you
say "do this" or "do it this way", but do not usually have to say
"do not do it that way") need to exist.

If I were writing this patch, I would rearrange the existing text
like so:

 * Update the description of "--no-rebase" *NOT* to depend on
   --rebase=false.  Instead move it higher and say

   - The default for "git pull" is to "merge" the other history into
     your history, but optionally you can "rebase" your history on
     top of the other history.

   - There are configuration variables (pull.rebase and
     branch.<name>.rebase) that trigger the optional behaviour, and
     when you set it, your "git pull" would "rebase".

   - The "--no-rebase" option is to defeat such configuration to
     tell the command to "merge" for this particular invocation.

 * Update the description of "--rebase=<kind>" and move the
   paragraph that begins with "When false" to the end, something
   like:

   - `--rebase` alone is equivalent to `--rebase=true`.
   - When set to 'merges'...
   - When set to 'interactive'...
   - See `pull.rebase`, ..., if you want to make `git pull` always
     rebase your history on top of theirs, instead of merging their
     history to yours.
   - `--rebase=false` is synonym to `--no-rebase`.