[RFC PATCH v2 6/7] git-rebase.txt: address confusion between --no-ff vs --force-rebase
- From
Elijah Newren <newren@gmail.com>
- Date
- Jun 17, 2018, 05:58 UTC
- Message-ID
- <20180617055856.22838-7-newren@gmail.com>
- In-Reply-To
- <20180617055856.22838-1-newren@gmail.com>
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> --- Documentation/git-rebase.txt | 35 ++++++++++------------------------- 1 file changed, 10 insertions(+), 25 deletions(-)
diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 0dbfab06d0..7a2ed9efdc 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -337,16 +337,18 @@ See also INCOMPATIBLE OPTIONS below. + See also INCOMPATIBLE OPTIONS below. --f:: +--no-ff:: --force-rebase:: - Force a rebase even if the current branch is up to date and - the command without `--force` would return without doing anything. +-f:: + Individually replay all rebased commits instead of fast-forwarding + over the unchanged ones. This ensures that the entire history of + the rebased branch is composed of new commits. + -You may find this (or --no-ff with an interactive rebase) helpful after -reverting a topic branch merge, as this option recreates the topic branch with -fresh commits so it can be remerged successfully without needing to "revert -the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). +You may find this helpful after reverting a topic branch merge, as this option +recreates the topic branch with fresh commits so it can be remerged +successfully without needing to "revert the reversion" (see the +link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for +details). --fork-point:: --no-fork-point:: @@ -498,18 +500,6 @@ See also INCOMPATIBLE OPTIONS below. with care: the final stash application after a successful rebase might result in non-trivial conflicts. ---no-ff:: - With --interactive, cherry-pick all rebased commits instead of - fast-forwarding over the unchanged ones. This ensures that the - entire history of the rebased branch is composed of new commits. -+ -Without --interactive, this is a synonym for --force-rebase. -+ -You may find this helpful after reverting a topic branch merge, as this option -recreates the topic branch with fresh commits so it can be remerged -successfully without needing to "revert the reversion" (see the -link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To] for details). - INCOMPATIBLE OPTIONS -------------------- @@ -558,11 +548,6 @@ Other incompatible flag pairs: BEHAVIORAL INCONSISTENCIES -------------------------- - * --no-ff vs. --force-rebase - - These options are actually identical, though their description - leads people to believe they might not be. - * empty commits: am-based rebase will drop any "empty" commits, whether the
-- 2.18.0.rc2.1.g5453d3f70b.dirty