summaryrefslogtreecommitdiff
path: root/Documentation/merge-strategies.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/merge-strategies.txt')
-rw-r--r--Documentation/merge-strategies.txt99
1 files changed, 58 insertions, 41 deletions
diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt
index 2912de706b..5fc54ec060 100644
--- a/Documentation/merge-strategies.txt
+++ b/Documentation/merge-strategies.txt
@@ -6,28 +6,23 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies
can also take their own options, which can be passed by giving `-X<option>`
arguments to `git merge` and/or `git pull`.
-resolve::
- This can only resolve two heads (i.e. the current branch
- and another branch you pulled from) using a 3-way merge
- algorithm. It tries to carefully detect criss-cross
- merge ambiguities and is considered generally safe and
- fast.
-
-recursive::
- This can only resolve two heads using a 3-way merge
- algorithm. When there is more than one common
- ancestor that can be used for 3-way merge, it creates a
- merged tree of the common ancestors and uses that as
- the reference tree for the 3-way merge. This has been
- reported to result in fewer merge conflicts without
- causing mismerges by tests done on actual merge commits
- taken from Linux 2.6 kernel development history.
- Additionally this can detect and handle merges involving
- renames, but currently cannot make use of detected
- copies. This is the default merge strategy when pulling
- or merging one branch.
+ort::
+ This is the default merge strategy when pulling or merging one
+ branch. This strategy can only resolve two heads using a
+ 3-way merge algorithm. When there is more than one common
+ ancestor that can be used for 3-way merge, it creates a merged
+ tree of the common ancestors and uses that as the reference
+ tree for the 3-way merge. This has been reported to result in
+ fewer merge conflicts without causing mismerges by tests done
+ on actual merge commits taken from Linux 2.6 kernel
+ development history. Additionally this strategy can detect
+ and handle merges involving renames. It does not make use of
+ detected copies. The name for this algorithm is an acronym
+ ("Ostensibly Recursive's Twin") and came from the fact that it
+ was written as a replacement for the previous default
+ algorithm, `recursive`.
+
-The 'recursive' strategy can take the following options:
+The 'ort' strategy can take the following options:
ours;;
This option forces conflicting hunks to be auto-resolved cleanly by
@@ -43,19 +38,6 @@ theirs;;
This is the opposite of 'ours'; note that, unlike 'ours', there is
no 'theirs' merge strategy to confuse this merge option with.
-patience;;
- With this option, 'merge-recursive' spends a little extra time
- to avoid mismerges that sometimes occur due to unimportant
- matching lines (e.g., braces from distinct functions). Use
- this when the branches to be merged have diverged wildly.
- See also linkgit:git-diff[1] `--patience`.
-
-diff-algorithm=[patience|minimal|histogram|myers];;
- Tells 'merge-recursive' to use a different diff algorithm, which
- can help avoid mismerges that occur due to unimportant matching
- lines (such as braces from distinct functions). See also
- linkgit:git-diff[1] `--diff-algorithm`.
-
ignore-space-change;;
ignore-all-space;;
ignore-space-at-eol;;
@@ -84,11 +66,6 @@ no-renormalize;;
Disables the `renormalize` option. This overrides the
`merge.renormalize` configuration variable.
-no-renames;;
- Turn off rename detection. This overrides the `merge.renames`
- configuration variable.
- See also linkgit:git-diff[1] `--no-renames`.
-
find-renames[=<n>];;
Turn on rename detection, optionally setting the similarity
threshold. This is the default. This overrides the
@@ -105,6 +82,46 @@ subtree[=<path>];;
is prefixed (or stripped from the beginning) to make the shape of
two trees to match.
+recursive::
+ This can only resolve two heads using a 3-way merge
+ algorithm. When there is more than one common
+ ancestor that can be used for 3-way merge, it creates a
+ merged tree of the common ancestors and uses that as
+ the reference tree for the 3-way merge. This has been
+ reported to result in fewer merge conflicts without
+ causing mismerges by tests done on actual merge commits
+ taken from Linux 2.6 kernel development history.
+ Additionally this can detect and handle merges involving
+ renames. It does not make use of detected copies. This was
+ the default strategy for resolving two heads from Git v0.99.9k
+ until v2.33.0.
++
+The 'recursive' strategy takes the same options as 'ort'. However,
+there are three additional options that 'ort' ignores (not documented
+above) that are potentially useful with the 'recursive' strategy:
+
+patience;;
+ Deprecated synonym for `diff-algorithm=patience`.
+
+diff-algorithm=[patience|minimal|histogram|myers];;
+ Use a different diff algorithm while merging, which can help
+ avoid mismerges that occur due to unimportant matching lines
+ (such as braces from distinct functions). See also
+ linkgit:git-diff[1] `--diff-algorithm`. Note that `ort`
+ specifically uses `diff-algorithm=histogram`, while `recursive`
+ defaults to the `diff.algorithm` config setting.
+
+no-renames;;
+ Turn off rename detection. This overrides the `merge.renames`
+ configuration variable.
+ See also linkgit:git-diff[1] `--no-renames`.
+
+resolve::
+ This can only resolve two heads (i.e. the current branch
+ and another branch you pulled from) using a 3-way merge
+ algorithm. It tries to carefully detect criss-cross
+ merge ambiguities. It does not handle renames.
+
octopus::
This resolves cases with more than two heads, but refuses to do
a complex merge that needs manual resolution. It is
@@ -121,13 +138,13 @@ ours::
the 'recursive' merge strategy.
subtree::
- This is a modified recursive strategy. When merging trees A and
+ This is a modified `ort` strategy. When merging trees A and
B, if B corresponds to a subtree of A, B is first adjusted to
match the tree structure of A, instead of reading the trees at
the same level. This adjustment is also done to the common
ancestor tree.
-With the strategies that use 3-way merge (including the default, 'recursive'),
+With the strategies that use 3-way merge (including the default, 'ort'),
if a change is made on both branches, but later reverted on one of the
branches, that change will be present in the merged result; some people find
this behavior confusing. It occurs because only the heads and the merge base