doc: convert merge strategies to synopsis format
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
May 25, 2025 at 20:27 UTC
179f877b88ce2a4f1c540f825741402e9c92915e
1 file changed
+29
-29
Documentation/merge-strategies.adoc
+29
-29
@@ -6,7 +6,7 @@ backend 'merge strategies' to be chosen with `-s` option. Some strategies
6
can also take their own options, which can be passed by giving `-X<option>`
7
arguments to `git merge` and/or `git pull`.
8
9
-ort::
9
+`ort`::
10
This is the default merge strategy when pulling or merging one
11
branch. This strategy can only resolve two heads using a
12
3-way merge algorithm. When there is more than one common
@@ -29,26 +29,26 @@ descendant. Otherwise, Git will treat this case as a conflict, suggesting
29
as a resolution a submodule commit that is descendant of the conflicting
30
ones, if one exists.
31
+
32
-The 'ort' strategy can take the following options:
32
+The `ort` strategy can take the following options:
33
34
-ours;;
34
+`ours`;;
35
This option forces conflicting hunks to be auto-resolved cleanly by
36
favoring 'our' version. Changes from the other tree that do not
37
conflict with our side are reflected in the merge result.
38
For a binary file, the entire contents are taken from our side.
39
+
40
-This should not be confused with the 'ours' merge strategy, which does not
40
+This should not be confused with the `ours` merge strategy, which does not
41
even look at what the other tree contains at all. It discards everything
42
the other tree did, declaring 'our' history contains all that happened in it.
43
44
-theirs;;
45
- This is the opposite of 'ours'; note that, unlike 'ours', there is
46
- no 'theirs' merge strategy to confuse this merge option with.
44
+`theirs`;;
45
+ This is the opposite of `ours`; note that, unlike `ours`, there is
46
+ no `theirs` merge strategy to confuse this merge option with.
47
48
-ignore-space-change;;
49
-ignore-all-space;;
50
-ignore-space-at-eol;;
51
-ignore-cr-at-eol;;
48
+`ignore-space-change`;;
49
+`ignore-all-space`;;
50
+`ignore-space-at-eol`;;
51
+`ignore-cr-at-eol`;;
52
Treats lines with the indicated type of whitespace change as
53
unchanged for the sake of a three-way merge. Whitespace
54
changes mixed with other changes to a line are not ignored.
@@ -61,7 +61,7 @@ ignore-cr-at-eol;;
61
version includes a substantial change, 'their' version is used;
62
* Otherwise, the merge proceeds in the usual way.
63
64
-renormalize;;
64
+`renormalize`;;
65
This runs a virtual check-out and check-in of all three stages
66
of any file which needs a three-way merge. This option is
67
meant to be used when merging branches with different clean
@@ -69,31 +69,31 @@ renormalize;;
69
branches with differing checkin/checkout attributes" in
70
linkgit:gitattributes[5] for details.
71
72
-no-renormalize;;
72
+`no-renormalize`;;
73
Disables the `renormalize` option. This overrides the
74
`merge.renormalize` configuration variable.
75
76
-find-renames[=<n>];;
76
+`find-renames[=<n>]`;;
77
Turn on rename detection, optionally setting the similarity
78
threshold. This is the default. This overrides the
79
- 'merge.renames' configuration variable.
79
+ `merge.renames` configuration variable.
80
See also linkgit:git-diff[1] `--find-renames`.
81
82
-rename-threshold=<n>;;
82
+`rename-threshold=<n>`;;
83
Deprecated synonym for `find-renames=<n>`.
84
85
-no-renames;;
85
+`no-renames`;;
86
Turn off rename detection. This overrides the `merge.renames`
87
configuration variable.
88
See also linkgit:git-diff[1] `--no-renames`.
89
90
-histogram;;
90
+`histogram`;;
91
Deprecated synonym for `diff-algorithm=histogram`.
92
93
-patience;;
93
+`patience`;;
94
Deprecated synonym for `diff-algorithm=patience`.
95
96
-diff-algorithm=[histogram|minimal|myers|patience];;
96
+`diff-algorithm=(histogram|minimal|myers|patience)`;;
97
Use a different diff algorithm while merging, which can help
98
avoid mismerges that occur due to unimportant matching lines
99
(such as braces from distinct functions). See also
@@ -101,49 +101,49 @@ diff-algorithm=[histogram|minimal|myers|patience];;
101
defaults to `diff-algorithm=histogram`, while regular diffs
102
currently default to the `diff.algorithm` config setting.
103
104
-subtree[=<path>];;
104
+`subtree[=<path>]`;;
105
This option is a more advanced form of 'subtree' strategy, where
106
the strategy makes a guess on how two trees must be shifted to
107
match with each other when merging. Instead, the specified path
108
is prefixed (or stripped from the beginning) to make the shape of
109
two trees to match.
110
111
-recursive::
111
+`recursive`::
112
This is now a synonym for `ort`. It was an alternative
113
implementation until v2.49.0, but was redirected to mean `ort`
114
in v2.50.0. The previous recursive strategy was the default
115
strategy for resolving two heads from Git v0.99.9k until
116
v2.33.0.
117
118
-resolve::
118
+`resolve`::
119
This can only resolve two heads (i.e. the current branch
120
and another branch you pulled from) using a 3-way merge
121
algorithm. It tries to carefully detect criss-cross
122
merge ambiguities. It does not handle renames.
123
124
-octopus::
124
+`octopus`::
125
This resolves cases with more than two heads, but refuses to do
126
a complex merge that needs manual resolution. It is
127
primarily meant to be used for bundling topic branch
128
heads together. This is the default merge strategy when
129
pulling or merging more than one branch.
130
131
-ours::
131
+`ours`::
132
This resolves any number of heads, but the resulting tree of the
133
merge is always that of the current branch head, effectively
134
ignoring all changes from all other branches. It is meant to
135
be used to supersede old development history of side
136
- branches. Note that this is different from the -Xours option to
137
- the 'ort' merge strategy.
136
+ branches. Note that this is different from the `-Xours` option to
137
+ the `ort` merge strategy.
138
139
-subtree::
139
+`subtree`::
140
This is a modified `ort` strategy. When merging trees A and
141
B, if B corresponds to a subtree of A, B is first adjusted to
142
match the tree structure of A, instead of reading the trees at
143
the same level. This adjustment is also done to the common
144
ancestor tree.
145
146
-With the strategies that use 3-way merge (including the default, 'ort'),
146
+With the strategies that use 3-way merge (including the default, `ort`),
147
if a change is made on both branches, but later reverted on one of the
148
branches, that change will be present in the merged result; some people find
149
this behavior confusing. It occurs because only the heads and the merge base