[PATCH v7 0/3] rebase: document, clean up, and introduce a config option for --rebase-merges

This patch series introduces a rebase.rebaseMerges config option to accommodate users who would like --rebase-merges to be on by default and to facilitate turning on --rebase-merges by default without configuration in a future version of Git. It also cleans up and documents the behavior of the --rebase-merges command line option to avoid confusion about how the config option and the command line option interact.

Changes from v6:
- Don't say that the default rebase-merges mode will likely change to
  rebase-cousins (although it might change to something else)
- In git-config.txt, say that rebase.rebaseMerges=true is equivalent
  to --rebase-merges=no-rebase-cousins
- Add a link from the revised paragraph in git-rebase.txt to the
  corresponding new section in git-config.txt
- Clear rebase_cousins if rebase.rebaseMerges is set to true after
  having been set to rebase-cousins or no-rebase-cousins
- Actually remove the test for --rebase-merges=""
- Remove the test for --rebase-merges=no-rebase-cousins overriding
  rebase.rebaseMerges=rebase-cousins

Suggestions on v6 not incorporated in v7:
- Make --rebase-merges without an argument clobber the mode specified in
  rebase.rebaseMerges
- In the tests, pass --force and check the graph itself or the reflog
  instead of checking that the graph has not changed by checking that
  the commit hash has not changed
- Add --rebase-merges=on as a synonym of
  --rebase-merges=no-rebase-cousins and --rebase-merges=off as a synonym
  of --no-rebase-merges
- Rewrite the documentation for rebase-cousins to more clearly explain
  the difference between rebase-cousins and no-rebase-cousins

Thanks to Phillip, Junio, Glen, and Sergey for your feedback on v6.

Alex Henrie (3):
  rebase: add documentation and test for --no-rebase-merges
  rebase: deprecate --rebase-merges=""
  rebase: add a config option for --rebase-merges

 Documentation/config/rebase.txt        | 11 ++++
 Documentation/git-rebase.txt           | 20 ++++---
 builtin/rebase.c                       | 76 +++++++++++++++++++-------
 t/t3422-rebase-incompatible-options.sh | 17 ++++++
 t/t3430-rebase-merges.sh               | 58 ++++++++++++++++++++
 5 files changed, 156 insertions(+), 26 deletions(-)

Range-diff against v6:
1:  bf08c03ba7 = 1:  3aee0c2277 rebase: add documentation and test for --no-rebase-merges
2:  26f98b8400 = 2:  e57843d8b5 rebase: deprecate --rebase-merges=""
3:  402365256c ! 3:  b0c1a4dcb2 rebase: add a config option for --rebase-merges
    @@ Commit message
         .gitconfig.
     
         In the future, the default rebase-merges mode may change from
    -    no-rebase-cousins to rebase-cousins. Support setting rebase.rebaseMerges
    -    to the nonspecific value "true" for users who do not need or want to
    -    care about the default changing in the future. Similarly, for users who
    -    have --rebase-merges in an alias and want to get the future behavior
    -    now, use the specific rebase-merges mode from the config if a specific
    -    mode is not given on the command line.
    +    no-rebase-cousins to some other mode that doesn't exist yet. Support
    +    setting rebase.rebaseMerges to the nonspecific value "true" for users
    +    who do not need or want to care about the default changing in the
    +    future. Similarly, for users who have --rebase-merges in an alias and
    +    want to get the future behavior now, use the specific rebase-merges mode
    +    from the config if a specific mode is not given on the command line.
     
         Signed-off-by: Alex Henrie <alexhenrie24@gmail.com>
     
    @@ Documentation/config/rebase.txt: rebase.rescheduleFailedExec::
     +rebase.rebaseMerges::
     +	Whether and how to set the `--rebase-merges` option by default. Can
     +	be `rebase-cousins`, `no-rebase-cousins`, or a boolean. Setting to
    -+	true is equivalent to `--rebase-merges` without an argument, setting to
    -+	`rebase-cousins` or `no-rebase-cousins` is equivalent to
    -+	`--rebase-merges` with that value as its argument, and setting to false
    -+	is equivalent to `--no-rebase-merges`. Passing `--rebase-merges` on the
    ++	true or to `no-rebase-cousins` is equivalent to
    ++	`--rebase-merges=no-rebase-cousins`, setting to `rebase-cousins` is
    ++	equivalent to `--rebase-merges=rebase-cousins`, and setting to false is
    ++	equivalent to `--no-rebase-merges`. Passing `--rebase-merges` on the
     +	command line without an argument overrides a `rebase.rebaseMerges=false`
     +	configuration, but the absence of a specific rebase-merges mode on the
     +	command line does not counteract a specific mode set in the configuration.
    @@ Documentation/git-rebase.txt: See also INCOMPATIBLE OPTIONS below.
     -such commits are instead rebased onto `<upstream>` (or `<onto>`, if
     -specified).
     +`no-rebase-cousins`. If the mode is not specified on the command line or in
    -+the `rebase.rebaseMerges` config option, it defaults to `no-rebase-cousins`.
    -+In `no-rebase-cousins` mode, commits which do not have `<upstream>` as direct
    ++the `rebase.rebaseMerges` config option (see linkgit:git-config[1] or
    ++"CONFIGURATION" below), it defaults to `no-rebase-cousins`. In
    ++`no-rebase-cousins` mode, commits which do not have `<upstream>` as direct
     +ancestor will keep their original branch point, i.e. commits that would be
     +excluded by linkgit:git-log[1]'s `--ancestry-path` option will keep their
     +original ancestry by default. In `rebase-cousins` mode, such commits are
    @@ builtin/rebase.c: static int rebase_config(const char *var, const char *value, v
     +		if (opts->config_rebase_merges < 0) {
     +			opts->config_rebase_merges = 1;
     +			parse_rebase_merges_value(opts, value);
    -+		}
    ++		} else
    ++			opts->rebase_cousins = 0;
     +		return 0;
     +	}
     +
    @@ t/t3430-rebase-merges.sh: test_expect_success 'do not rebase cousins unless aske
      	EOF
      '
      
    -+test_expect_success '--rebase-merges="" is deprecated' '
    -+	git rebase --rebase-merges="" HEAD^ 2>actual &&
    -+	grep deprecated actual
    -+'
    -+
     +test_expect_success 'rebase.rebaseMerges=rebase-cousins is equivalent to --rebase-merges=rebase-cousins' '
     +	test_config rebase.rebaseMerges rebase-cousins &&
     +	git checkout -b config-rebase-cousins main &&
    @@ t/t3430-rebase-merges.sh: test_expect_success 'do not rebase cousins unless aske
     +	EOF
     +'
     +
    -+test_expect_success '--rebase-merges=no-rebase-cousins overrides rebase.rebaseMerges=rebase-cousins' '
    -+	test_config rebase.rebaseMerges rebase-cousins &&
    -+	git checkout -b override-config-rebase-cousins main &&
    -+	git rebase --rebase-merges=no-rebase-cousins HEAD^ &&
    -+	test_cmp_graph HEAD^.. <<-\EOF
    -+	*   Merge the topic branch '\''onebranch'\''
    -+	|\
    -+	| * D
    -+	| * G
    -+	o | H
    -+	|/
    -+	o A
    -+	EOF
    -+'
    -+
     +test_expect_success '--rebase-merges overrides rebase.rebaseMerges=false' '
     +	test_config rebase.rebaseMerges false &&
     +	git checkout -b override-config-merges-false E &&