Documentation: point to related commands from gitignore
[gitweb.git] / Documentation / merge-strategies.txt
index 42910a3d5e0229f471c5bceb0c36f184d17ebb08..8676e26ca20311196d069ab28c08c913271c7631 100644 (file)
@@ -1,6 +1,11 @@
 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
@@ -20,6 +25,39 @@ recursive::
        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.
++
+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 opposite of 'ours'.
+
+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.
+
+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
@@ -33,7 +71,8 @@ ours::
        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.
+       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