doc: convert merge options to new synopsis format
- 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
5f3213232fa052e62b6ec33447aa50936ef1e232
2 files changed
+56
-56
Documentation/merge-options.adoc
+54
-54
@@ -1,23 +1,23 @@
1
---commit::
2
---no-commit::
1
+`--commit`::
2
+`--no-commit`::
3
Perform the merge and commit the result. This option can
4
- be used to override --no-commit.
4
+ be used to override `--no-commit`.
5
ifdef::git-pull[]
6
Only useful when merging.
7
endif::git-pull[]
8
+
9
-With --no-commit perform the merge and stop just before creating
9
+With `--no-commit` perform the merge and stop just before creating
10
a merge commit, to give the user a chance to inspect and further
11
tweak the merge result before committing.
12
+
13
Note that fast-forward updates do not create a merge commit and
14
-therefore there is no way to stop those merges with --no-commit.
14
+therefore there is no way to stop those merges with `--no-commit`.
15
Thus, if you want to ensure your branch is not changed or updated
16
-by the merge command, use --no-ff with --no-commit.
16
+by the merge command, use `--no-ff` with `--no-commit`.
17
18
---edit::
19
--e::
20
---no-edit::
18
+`--edit`::
19
+`-e`::
20
+`--no-edit`::
21
Invoke an editor before committing successful mechanical merge to
22
further edit the auto-generated merge message, so that the user
23
can explain and justify the merge. The `--no-edit` option can be
@@ -35,17 +35,17 @@ they run `git merge`. To make it easier to adjust such scripts to the
35
updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be
36
set to `no` at the beginning of them.
37
38
---cleanup=<mode>::
38
+`--cleanup=<mode>`::
39
This option determines how the merge message will be cleaned up before
40
committing. See linkgit:git-commit[1] for more details. In addition, if
41
- the '<mode>' is given a value of `scissors`, scissors will be appended
41
+ the _<mode>_ is given a value of `scissors`, scissors will be appended
42
to `MERGE_MSG` before being passed on to the commit machinery in the
43
case of a merge conflict.
44
45
ifdef::git-merge[]
46
---ff::
47
---no-ff::
48
---ff-only::
46
+`--ff`::
47
+`--no-ff`::
48
+`--ff-only`::
49
Specifies how a merge is handled when the merged-in history is
50
already a descendant of the current history. `--ff` is the
51
default unless merging an annotated (and possibly signed) tag
@@ -53,13 +53,13 @@ ifdef::git-merge[]
53
hierarchy, in which case `--no-ff` is assumed.
54
endif::git-merge[]
55
ifdef::git-pull[]
56
---ff-only::
56
+`--ff-only`::
57
Only update to the new history if there is no divergent local
58
history. This is the default when no method for reconciling
59
divergent histories is provided (via the --rebase=* flags).
60
61
---ff::
62
---no-ff::
61
+`--ff`::
62
+`--no-ff`::
63
When merging rather than rebasing, specifies how a merge is
64
handled when the merged-in history is already a descendant of
65
the current history. If merging is requested, `--ff` is the
@@ -81,40 +81,40 @@ With `--ff-only`, resolve the merge as a fast-forward when possible.
81
When not possible, refuse to merge and exit with a non-zero status.
82
endif::git-merge[]
83
84
--S[<keyid>]::
85
---gpg-sign[=<keyid>]::
86
---no-gpg-sign::
87
- GPG-sign the resulting merge commit. The `keyid` argument is
84
+`-S[<key-id>]`::
85
+`--gpg-sign[=<key-id>]`::
86
+`--no-gpg-sign`::
87
+ GPG-sign the resulting merge commit. The _<key-id>_ argument is
88
optional and defaults to the committer identity; if specified,
89
it must be stuck to the option without a space. `--no-gpg-sign`
90
is useful to countermand both `commit.gpgSign` configuration variable,
91
and earlier `--gpg-sign`.
92
93
---log[=<n>]::
94
---no-log::
93
+`--log[=<n>]`::
94
+`--no-log`::
95
In addition to branch names, populate the log message with
96
- one-line descriptions from at most <n> actual commits that are being
96
+ one-line descriptions from at most _<n>_ actual commits that are being
97
merged. See also linkgit:git-fmt-merge-msg[1].
98
ifdef::git-pull[]
99
Only useful when merging.
100
endif::git-pull[]
101
+
102
-With --no-log do not list one-line descriptions from the
102
+With `--no-log` do not list one-line descriptions from the
103
actual commits being merged.
104
105
include::signoff-option.adoc[]
106
107
---stat::
108
--n::
109
---no-stat::
107
+`--stat`::
108
+`-n`::
109
+`--no-stat`::
110
Show a diffstat at the end of the merge. The diffstat is also
111
controlled by the configuration option merge.stat.
112
+
113
-With -n or --no-stat do not show a diffstat at the end of the
113
+With `-n` or `--no-stat` do not show a diffstat at the end of the
114
merge.
115
116
---squash::
117
---no-squash::
116
+`--squash`::
117
+`--no-squash`::
118
Produce the working tree and index state as if a real merge
119
happened (except for the merge information), but do not actually
120
make a commit, move the `HEAD`, or record `$GIT_DIR/MERGE_HEAD`
@@ -123,16 +123,16 @@ merge.
123
the current branch whose effect is the same as merging another
124
branch (or more in case of an octopus).
125
+
126
-With --no-squash perform the merge and commit the result. This
127
-option can be used to override --squash.
126
+With `--no-squash` perform the merge and commit the result. This
127
+option can be used to override `--squash`.
128
+
129
-With --squash, --commit is not allowed, and will fail.
129
+With `--squash`, `--commit` is not allowed, and will fail.
130
ifdef::git-pull[]
131
+
132
Only useful when merging.
133
endif::git-pull[]
134
135
---[no-]verify::
135
+`--[no-]verify`::
136
By default, the pre-merge and commit-msg hooks are run.
137
When `--no-verify` is given, these are bypassed.
138
See also linkgit:githooks[5].
@@ -140,21 +140,21 @@ ifdef::git-pull[]
140
Only useful when merging.
141
endif::git-pull[]
142
143
--s <strategy>::
144
---strategy=<strategy>::
143
+`-s <strategy>`::
144
+`--strategy=<strategy>`::
145
Use the given merge strategy; can be supplied more than
146
once to specify them in the order they should be tried.
147
If there is no `-s` option, a built-in list of strategies
148
is used instead (`ort` when merging a single head,
149
`octopus` otherwise).
150
151
--X <option>::
152
---strategy-option=<option>::
151
+`-X <option>`::
152
+`--strategy-option=<option>`::
153
Pass merge strategy specific option through to the merge
154
strategy.
155
156
---verify-signatures::
157
---no-verify-signatures::
156
+`--verify-signatures`::
157
+`--no-verify-signatures`::
158
Verify that the tip commit of the side branch being merged is
159
signed with a valid key, i.e. a key that has a valid uid: in the
160
default trust model, this means the signing key has been signed by
@@ -165,22 +165,22 @@ ifdef::git-pull[]
165
Only useful when merging.
166
endif::git-pull[]
167
168
---summary::
169
---no-summary::
170
- Synonyms to --stat and --no-stat; these are deprecated and will be
168
+`--summary`::
169
+`--no-summary`::
170
+ Synonyms to `--stat` and `--no-stat`; these are deprecated and will be
171
removed in the future.
172
173
ifndef::git-pull[]
174
--q::
175
---quiet::
176
- Operate quietly. Implies --no-progress.
174
+`-q`::
175
+`--quiet`::
176
+ Operate quietly. Implies `--no-progress`.
177
178
--v::
179
---verbose::
178
+`-v`::
179
+`--verbose`::
180
Be verbose.
181
182
---progress::
183
---no-progress::
182
+`--progress`::
183
+`--no-progress`::
184
Turn progress on/off explicitly. If neither is specified,
185
progress is shown if standard error is connected to a terminal.
186
Note that not all merge strategies may support progress
@@ -188,8 +188,8 @@ ifndef::git-pull[]
188
189
endif::git-pull[]
190
191
---autostash::
192
---no-autostash::
191
+`--autostash`::
192
+`--no-autostash`::
193
Automatically create a temporary stash entry before the operation
194
begins, record it in the ref `MERGE_AUTOSTASH`
195
and apply it after the operation ends. This means
@@ -197,7 +197,7 @@ endif::git-pull[]
197
with care: the final stash application after a successful
198
merge might result in non-trivial conflicts.
199
200
---allow-unrelated-histories::
200
+`--allow-unrelated-histories`::
201
By default, `git merge` command refuses to merge histories
202
that do not share a common ancestor. This option can be
203
used to override this safety when merging histories of two
Documentation/rerere-options.adoc
+2
-2
@@ -1,5 +1,5 @@
1
---rerere-autoupdate::
2
---no-rerere-autoupdate::
1
+`--rerere-autoupdate`::
2
+`--no-rerere-autoupdate`::
3
After the rerere mechanism reuses a recorded resolution on
4
the current conflict to update the files in the working
5
tree, allow it to also update the index with the result of