| MERGE STRATEGIES |
| ---------------- |
| |
| The merge mechanism (`git merge` and `git pull` commands) allows the |
| 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. This is the default merge strategy when |
| pulling or merging one branch. |
| + |
| The 'recursive' strategy can take the following options: |
| |
| ours;; |
| This option forces conflicting hunks to be auto-resolved cleanly by |
| favoring 'our' version. Changes from the other tree that do not |
| conflict with our side are reflected to the merge result. |
| For a binary file, the entire contents are taken from our side. |
| + |
| This should not be confused with the 'ours' merge strategy, which does not |
| even look at what the other tree contains at all. It discards everything |
| the other tree did, declaring 'our' history contains all that happened in it. |
| |
| theirs;; |
| This is the opposite of 'ours'. |
| |
| 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;; |
| Treats lines with the indicated type of whitespace change as |
| unchanged for the sake of a three-way merge. Whitespace |
| changes mixed with other changes to a line are not ignored. |
| See also linkgit:git-diff[1] `-b`, `-w`, and |
| `--ignore-space-at-eol`. |
| + |
| * If 'their' version only introduces whitespace changes to a line, |
| 'our' version is used; |
| * If 'our' version introduces whitespace changes but 'their' |
| version includes a substantial change, 'their' version is used; |
| * Otherwise, the merge proceeds in the usual way. |
| |
| renormalize;; |
| This runs a virtual check-out and check-in of all three stages |
| of a file when resolving a three-way merge. This option is |
| meant to be used when merging branches with different clean |
| filters or end-of-line normalization rules. See "Merging |
| branches with differing checkin/checkout attributes" in |
| linkgit:gitattributes[5] for details. |
| |
| no-renormalize;; |
| Disables the `renormalize` option. This overrides the |
| `merge.renormalize` configuration variable. |
| |
| no-renames;; |
| Turn off rename detection. |
| See also linkgit:git-diff[1] `--no-renames`. |
| |
| find-renames[=<n>];; |
| Turn on rename detection, optionally setting the similarity |
| threshold. This is the default. |
| See also linkgit:git-diff[1] `--find-renames`. |
| |
| rename-threshold=<n>;; |
| Deprecated synonym for `find-renames=<n>`. |
| |
| subtree[=<path>];; |
| This option is a more advanced form of 'subtree' strategy, where |
| the strategy makes a guess on how two trees must be shifted to |
| match with each other when merging. Instead, the specified path |
| is prefixed (or stripped from the beginning) to make the shape of |
| two trees to match. |
| |
| octopus:: |
| This resolves cases with more than two heads, but refuses to do |
| a complex merge that needs manual resolution. It is |
| primarily meant to be used for bundling topic branch |
| heads together. This is the default merge strategy when |
| pulling or merging more than one branch. |
| |
| ours:: |
| This resolves any number of heads, but the resulting tree of the |
| merge is always that of the current branch head, effectively |
| ignoring all changes from all other branches. It is meant to |
| be used to supersede old development history of side |
| branches. Note that this is different from the -Xours option to |
| the 'recursive' merge strategy. |
| |
| subtree:: |
| This is a modified recursive 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'), |
| 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 |
| are considered when performing a merge, not the individual commits. The merge |
| algorithm therefore considers the reverted change as no change at all, and |
| substitutes the changed version instead. |