summaryrefslogtreecommitdiff
path: root/Documentation/git-rebase.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-rebase.txt')
-rw-r--r--Documentation/git-rebase.txt77
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/