git-rebase.txt: address confusion between --no-ff vs --force-rebase

rebase was taught the --force-rebase option in commit b2f82e05de ("Teach rebase to rebase even if upstream is up to date", 2009-02-13). This flag worked for the am and merge backends, but wasn't a valid option for the interactive backend. rebase was taught the --no-ff option for interactive rebases in commit b499549401cb ("Teach rebase the --no-ff option.", 2010-03-24), to do the exact same thing as --force-rebase does for non-interactive rebases. This commit explicitly documented the fact that --force-rebase was incompatible with --interactive, though it made --no-ff a synonym for --force-rebase for non-interactive rebases. The choice of a new option was based on the fact that "force rebase" didn't sound like an appropriate term for the interactive machinery. In commit 6bb4e485cff8 ("rebase: align variable names", 2011-02-06), the separate parsing of command line options in the different rebase scripts was removed, and whether on accident or because the author noticed that these options did the same thing, the options became synonyms and both were accepted by all three rebase types. In commit 2d26d533a012 ("Documentation/git-rebase.txt: -f forces a rebase that would otherwise be a no-op", 2014-08-12), which reworded the description of the --force-rebase option, the (no-longer correct) sentence stating that --force-rebase was incompatible with --interactive was finally removed. Finally, as explained at https://public-inbox.org/git/98279912-0f52-969d-44a6-22242039387f@xiplink.com In the original discussion around this option [1], at one point I proposed teaching rebase--interactive to respect --force-rebase instead of adding a new option [2]. Ultimately --no-ff was chosen as the better user interface design [3], because an interactive rebase can't be "forced" to run. We have accepted both --no-ff and --force-rebase as full synonyms for all three rebase types for over seven years. Documenting them differently and in ways that suggest they might not be quite synonyms simply leads to confusion. Adjust the documentation to match reality. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Elijah Newren committed Jun 27, 2018 at 00:23 UTC 983f464fcbab700a2cac6011fa6941dab839548d
1 file changed +10 -20
Documentation/git-rebase.txt
+10 -20
@@ -337,16 +337,18 @@ See also INCOMPATIBLE OPTIONS below.
337 +
338 See also INCOMPATIBLE OPTIONS below.
339
340 --f::
340 +--no-ff::
341 --force-rebase::
342 - Force a rebase even if the current branch is up to date and
343 - the command without `--force` would return without doing anything.
342 +-f::
343 + Individually replay all rebased commits instead of fast-forwarding
344 + over the unchanged ones. This ensures that the entire history of
345 + the rebased branch is composed of new commits.
346 +
345 -You may find this (or --no-ff with an interactive rebase) helpful after
346 -reverting a topic branch merge, as this option recreates the topic branch with
347 -fresh commits so it can be remerged successfully without needing to "revert
348 -the reversion" (see the
349 -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
347 +You may find this helpful after reverting a topic branch merge, as this option
348 +recreates the topic branch with fresh commits so it can be remerged
349 +successfully without needing to "revert the reversion" (see the
350 +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for
351 +details).
352
353 --fork-point::
354 --no-fork-point::
@@ -498,18 +500,6 @@ See also INCOMPATIBLE OPTIONS below.
500 with care: the final stash application after a successful
501 rebase might result in non-trivial conflicts.
502
501 ---no-ff::
502 - With --interactive, cherry-pick all rebased commits instead of
503 - fast-forwarding over the unchanged ones. This ensures that the
504 - entire history of the rebased branch is composed of new commits.
505 -+
506 -Without --interactive, this is a synonym for --force-rebase.
507 -+
508 -You may find this helpful after reverting a topic branch merge, as this option
509 -recreates the topic branch with fresh commits so it can be remerged
510 -successfully without needing to "revert the reversion" (see the
511 -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details).
512 -
503 INCOMPATIBLE OPTIONS
504 --------------------
505