rebase: rename the two primary rebase backends

Two related changes, with separate rationale for each:

Rename the 'interactive' backend to 'merge' because:
  * 'interactive' as a name caused confusion; this backend has been used
    for many kinds of non-interactive rebases, and will probably be used
    in the future for more non-interactive rebases than interactive ones
    given that we are making it the default.
  * 'interactive' is not the underlying strategy; merging is.
  * the directory where state is stored is not called
    .git/rebase-interactive but .git/rebase-merge.

Rename the 'am' backend to 'apply' because:
  * Few users are familiar with git-am as a reference point.
  * Related to the above, the name 'am' makes sentences in the
    documentation harder for users to read and comprehend (they may read
    it as the verb from "I am"); avoiding this difficult places a large
    burden on anyone writing documentation about this backend to be very
    careful with quoting and sentence structure and often forces
    annoying redundancy to try to avoid such problems.
  * Users stumble over pronunciation ("am" as in "I am a person not a
    backend" or "am" as in "the first and thirteenth letters in the
    alphabet in order are "A-M"); this may drive confusion when one user
    tries to explain to another what they are doing.
  * While "am" is the tool driving this backend, the tool driving git-am
    is git-apply, and since we are driving towards lower-level tools
    for the naming of the merge backend we may as well do so here too.
  * The directory where state is stored has never been called
    .git/rebase-am, it was always called .git/rebase-apply.

For all the reasons listed above:
  * Modify the documentation to refer to the backends with the new names
  * Provide a brief note in the documentation connecting the new names
    to the old names in case users run across the old names anywhere
    (e.g. in old release notes or older versions of the documentation)
  * Change the (new) --am command line flag to --apply
  * Rename some enums, variables, and functions to reinforce the new
    backend names for us as well.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 41 insertions, 36 deletions

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index fbac1cf..8c1f4b8 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -258,10 +258,10 @@ See also INCOMPATIBLE OPTIONS below.
 	original branch. The index and working tree are also left
 	unchanged as a result.
 
---am:
-	Use git-am internally to rebase.  This option may become a
-	no-op in the future once the interactive backend handles
-	everything the am one does.
+--apply:
+	Use applying strategies to rebase (calling `git-am`
+	internally).  This option may become a no-op in the future
+	once the merge backend handles everything the apply one does.
 +
 See also INCOMPATIBLE OPTIONS below.
 
@@ -385,7 +385,7 @@ See also INCOMPATIBLE OPTIONS below.
 	Ensure at least <n> lines of surrounding context match before
 	and after each change.  When fewer lines of surrounding
 	context exist they all must match.  By default no context is
-	ever ignored.  Implies --am.
+	ever ignored.  Implies --apply.
 +
 See also INCOMPATIBLE OPTIONS below.
 
@@ -425,7 +425,7 @@ with `--keep-base` in order to drop those commits from your branch.
 --whitespace=<option>::
 	These flags are passed to the 'git apply' program
 	(see linkgit:git-apply[1]) that applies the patch.
-	Implies --am.
+	Implies --apply.
 +
 See also INCOMPATIBLE OPTIONS below.
 
@@ -569,7 +569,7 @@ INCOMPATIBLE OPTIONS
 
 The following options:
 
- * --am
+ * --apply
  * --committer-date-is-author-date
  * --ignore-date
  * --ignore-whitespace
@@ -604,42 +604,48 @@ In addition, the following pairs of options are incompatible:
 BEHAVIORAL DIFFERENCES
 -----------------------
 
-There are some subtle differences how the backends behave.
+git rebase has two primary backends: apply and merge.  (The apply
+backend used to known as the 'am' backend, but the name led to
+confusion as it looks like a verb instead of a noun.  Also, the merge
+backend used to be known as the interactive backend, but it is now
+used for non-interactive cases as well.  Both were renamed based on
+lower-level functionality that underpinned each.) There are some
+subtle differences in how these two backends behave:
 
 Empty commits
 ~~~~~~~~~~~~~
 
-The am backend unfortunately drops intentionally empty commits, i.e.
+The apply backend unfortunately drops intentionally empty commits, i.e.
 commits that started empty, though these are rare in practice.  It
 also drops commits that become empty and has no option for controlling
 this behavior.
 
-The interactive backend keeps intentionally empty commits.  Similar to
-the am backend, by default the interactive backend drops commits that
-become empty unless -i/--interactive is specified (in which case it
-stops and asks the user what to do).  The interactive backend also has
-an --empty={drop,keep,ask} option for changing the behavior of
-handling commits that become empty.
+The merge backend keeps intentionally empty commits.  Similar to the
+apply backend, by default the merge backend drops commits that become
+empty unless -i/--interactive is specified (in which case it stops and
+asks the user what to do).  The merge backend also has an
+--empty={drop,keep,ask} option for changing the behavior of handling
+commits that become empty.
 
 Directory rename detection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Due to the lack of accurate tree information (arising from
 constructing fake ancestors with the limited information available in
-patches), directory rename detection is disabled in the am backend.
+patches), directory rename detection is disabled in the apply backend.
 Disabled directory rename detection means that if one side of history
 renames a directory and the other adds new files to the old directory,
 then the new files will be left behind in the old directory without
 any warning at the time of rebasing that you may want to move these
 files into the new directory.
 
-Directory rename detection works with the merge and interactive
-backends to provide you warnings in such cases.
+Directory rename detection works with the merge backend to provide you
+warnings in such cases.
 
 Context
 ~~~~~~~
 
-The am backend works by creating a sequence of patches (by calling
+The apply backend works by creating a sequence of patches (by calling
 `format-patch` internally), and then applying the patches in sequence
 (calling `am` internally).  Patches are composed of multiple hunks,
 each with line numbers, a context region, and the actual changes.  The
@@ -654,7 +660,7 @@ Setting diff.context to a larger value may prevent such types of
 problems, but increases the chance of spurious conflicts (since it
 will require more lines of matching context to apply).
 
-The interactive backend works with a full copy of each relevant file,
+The merge backend works with a full copy of each relevant file,
 insulating it from these types of problems.
 
 Labelling of conflicts markers
@@ -662,34 +668,33 @@ Labelling of conflicts markers
 
 When there are content conflicts, the merge machinery tries to
 annotate each side's conflict markers with the commits where the
-content came from.  Since the am backend drops the original
+content came from.  Since the apply backend drops the original
 information about the rebased commits and their parents (and instead
 generates new fake commits based off limited information in the
 generated patches), those commits cannot be identified; instead it has
 to fall back to a commit summary.  Also, when merge.conflictStyle is
-set to diff3, the am backend will use "constructed merge base" to
+set to diff3, the apply backend will use "constructed merge base" to
 label the content from the merge base, and thus provide no information
 about the merge base commit whatsoever.
 
-The interactive backend works with the full commits on both sides of
-history and thus has no such limitations.
+The merge backend works with the full commits on both sides of history
+and thus has no such limitations.
 
 Hooks
 ~~~~~
 
-The am backend has not traditionally called the post-commit hook,
-while the merge/interactive backend has.  However, this was by
-accident of implementation rather than by design.  Both backends
-should have the same behavior, though it is not clear which one is
-correct.
+The apply backend has not traditionally called the post-commit hook,
+while the merge backend has.  However, this was by accident of
+implementation rather than by design.  Both backends should have the
+same behavior, though it is not clear which one is correct.
 
 Interruptability
 ~~~~~~~~~~~~~~~~
 
-The am backend has safety problems with an ill-timed interrupt; if the
-user presses Ctrl-C at the wrong time to try to abort the rebase, the
-rebase can enter a state where it cannot be aborted with a subsequent
-`git rebase --abort`.  The interactive backend does not appear to
+The apply backend has safety problems with an ill-timed interrupt; if
+the user presses Ctrl-C at the wrong time to try to abort the rebase,
+the rebase can enter a state where it cannot be aborted with a
+subsequent `git rebase --abort`.  The merge backend does not appear to
 suffer from the same shortcoming.  (See
 https://lore.kernel.org/git/20200207132152.GC2868@szeder.dev/ for
 details.)
@@ -707,9 +712,9 @@ completeness:
 
 * Progress, informational, and error messages: The two backends
   provide slightly different progress and informational messages.
-  Also, the am backend writes error messages (such as "Your files
-  would be overwritten...") to stdout, while the interactive backend
-  writes them to stderr.
+  Also, the apply backend writes error messages (such as "Your files
+  would be overwritten...") to stdout, while the merge backend writes
+  them to stderr.
 
 * State directories: The two backends keep their state in different
   directories under .git/