Junio C Hamano <gitster@xxxxxxxxx> writes:
Dragan Simic <dsimic@xxxxxxxxxxx> 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".
