doc: convert git-merge manpage to new style
- 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. In order to avoid breaking the format on '<<<<<<' and '>>>>>' lines by applying the synopsis rules to these spans, they are formatted using '+' signs instead of '`' signs. 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
13d5331cccf8c23f1d4eb9b6a24e2308c8631d00
1 file changed
+25
-26
Documentation/git-merge.adoc
+25
-26
@@ -8,13 +8,13 @@ git-merge - Join two or more development histories together
8
9
SYNOPSIS
10
--------
11
-[verse]
12
-'git merge' [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
11
+[synopsis]
12
+git merge [-n] [--stat] [--no-commit] [--squash] [--[no-]edit]
13
[--no-verify] [-s <strategy>] [-X <strategy-option>] [-S[<keyid>]]
14
[--[no-]allow-unrelated-histories]
15
[--[no-]rerere-autoupdate] [-m <msg>] [-F <file>]
16
[--into-name <branch>] [<commit>...]
17
-'git merge' (--continue | --abort | --quit)
17
+git merge (--continue | --abort | --quit)
18
19
DESCRIPTION
20
-----------
@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
57
after the merge was started), `git merge --abort` will in some cases be
58
unable to reconstruct the original (pre-merge) changes. Therefore:
59
60
-*Warning*: Running `git merge` with non-trivial uncommitted changes is
60
+WARNING: Running `git merge` with non-trivial uncommitted changes is
61
discouraged: while possible, it may leave you in a state that is hard to
62
back out of in the case of a conflict.
63
@@ -67,7 +67,7 @@ OPTIONS
67
68
include::merge-options.adoc[]
69
70
--m <msg>::
70
+`-m <msg>`::
71
Set the commit message to be used for the merge commit (in
72
case one is created).
73
+
@@ -78,13 +78,13 @@ The `git fmt-merge-msg` command can be
78
used to give a good default for automated `git merge`
79
invocations. The automated message can include the branch description.
80
81
---into-name <branch>::
81
+`--into-name <branch>`::
82
Prepare the default merge message as if merging to the branch
83
- `<branch>`, instead of the name of the real branch to which
83
+ _<branch>_, instead of the name of the real branch to which
84
the merge is made.
85
86
--F <file>::
87
---file=<file>::
86
+`-F <file>`::
87
+`--file=<file>`::
88
Read the commit message to be used for the merge commit (in
89
case one is created).
90
+
@@ -93,12 +93,12 @@ will be appended to the specified message.
93
94
include::rerere-options.adoc[]
95
96
---overwrite-ignore::
97
---no-overwrite-ignore::
96
+`--overwrite-ignore`::
97
+`--no-overwrite-ignore`::
98
Silently overwrite ignored files from the merge result. This
99
is the default behavior. Use `--no-overwrite-ignore` to abort.
100
101
---abort::
101
+`--abort`::
102
Abort the current conflict resolution process, and
103
try to reconstruct the pre-merge state. If an autostash entry is
104
present, apply it to the worktree.
@@ -114,17 +114,17 @@ which case `git merge --abort` applies the stash entry to the worktree
114
whereas `git reset --merge` will save the stashed changes in the stash
115
list.
116
117
---quit::
117
+`--quit`::
118
Forget about the current merge in progress. Leave the index
119
and the working tree as-is. If `MERGE_AUTOSTASH` is present, the
120
stash entry will be saved to the stash list.
121
122
---continue::
122
+`--continue`::
123
After a `git merge` stops due to conflicts you can conclude the
124
merge by running `git merge --continue` (see "HOW TO RESOLVE
125
CONFLICTS" section below).
126
127
-<commit>...::
127
+`<commit>...`::
128
Commits, usually other branch heads, to merge into our branch.
129
Specifying more than one commit will create a merge with
130
more than two parents (affectionately called an Octopus merge).
@@ -152,7 +152,7 @@ To avoid recording unrelated changes in the merge commit,
152
`git pull` and `git merge` will also abort if there are any changes
153
registered in the index relative to the `HEAD` commit. (Special
154
narrow exceptions to this rule may exist depending on which merge
155
-strategy is in use, but generally, the index must match HEAD.)
155
+strategy is in use, but generally, the index must match `HEAD`.)
156
157
If all named commits are already ancestors of `HEAD`, `git merge`
158
will exit early with the message "Already up to date."
@@ -195,11 +195,11 @@ happens:
195
stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
196
can inspect the stages with `git ls-files -u`). The working
197
tree files contain the result of the merge operation; i.e. 3-way
198
- merge results with familiar conflict markers `<<<` `===` `>>>`.
198
+ merge results with familiar conflict markers +<<<+ `===` +>>>+.
199
5. A ref named `AUTO_MERGE` is written, pointing to a tree
200
corresponding to the current content of the working tree (including
201
conflict markers for textual conflicts). Note that this ref is only
202
- written when the 'ort' merge strategy is used (the default).
202
+ written when the `ort` merge strategy is used (the default).
203
6. No other changes are made. In particular, the local
204
modifications you had before you started merge will stay the
205
same and the index entries for them stay as they were,
@@ -231,7 +231,6 @@ git merge v1.2.3^0
231
git merge --ff-only v1.2.3
232
----
233
234
-
234
HOW CONFLICTS ARE PRESENTED
235
---------------------------
236
@@ -260,7 +259,7 @@ And here is another line that is cleanly resolved or unmodified.
259
------------
260
261
The area where a pair of conflicting changes happened is marked with markers
263
-`<<<<<<<`, `=======`, and `>>>>>>>`. The part before the `=======`
262
++<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======`
263
is typically your side, and the part afterwards is typically their side.
264
265
The default format does not show what the original said in the conflicting
@@ -270,7 +269,7 @@ side wants to say it is hard and you'd prefer to go shopping, while the
269
other side wants to claim it is easy.
270
271
An alternative style can be used by setting the `merge.conflictStyle`
273
-configuration variable to either "diff3" or "zdiff3". In "diff3"
272
+configuration variable to either `diff3` or `zdiff3`. In `diff3`
273
style, the above conflict may look like this:
274
275
------------
@@ -290,7 +289,7 @@ Git makes conflict resolution easy.
289
And here is another line that is cleanly resolved or unmodified.
290
------------
291
293
-while in "zdiff3" style, it may look like this:
292
+while in `zdiff3` style, it may look like this:
293
294
------------
295
Here are lines that are either unchanged from the common
@@ -308,8 +307,8 @@ Git makes conflict resolution easy.
307
And here is another line that is cleanly resolved or unmodified.
308
------------
309
311
-In addition to the `<<<<<<<`, `=======`, and `>>>>>>>` markers, it uses
312
-another `|||||||` marker that is followed by the original text. You can
310
+In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses
311
+another +|||||||+ marker that is followed by the original text. You can
312
tell that the original just stated a fact, and your side simply gave in to
313
that statement and gave up, while the other side tried to have a more
314
positive attitude. You can sometimes come up with a better resolution by
@@ -390,8 +389,8 @@ include::merge-strategies.adoc[]
389
CONFIGURATION
390
-------------
391
393
-branch.<name>.mergeOptions::
394
- Sets default options for merging into branch <name>. The syntax and
392
+`branch.<name>.mergeOptions`::
393
+ Sets default options for merging into branch _<name>_. The syntax and
394
supported options are the same as those of `git merge`, but option
395
values containing whitespace characters are currently not supported.
396