doc: convert git-notes to new documentation 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
Jan 10, 2025 at 10:08 UTC
77b2d29e91c568dc3b08adbfc48fea641d4e39f7
2 files changed
+112
-111
Documentation/config/notes.txt
+16
-16
@@ -1,4 +1,4 @@
1
-notes.mergeStrategy::
1
+`notes.mergeStrategy`::
2
Which merge strategy to choose by default when resolving notes
3
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
4
`cat_sort_uniq`. Defaults to `manual`. See the "NOTES MERGE STRATEGIES"
@@ -7,17 +7,17 @@ notes.mergeStrategy::
7
This setting can be overridden by passing the `--strategy` option to
8
linkgit:git-notes[1].
9
10
-notes.<name>.mergeStrategy::
10
+`notes.<name>.mergeStrategy`::
11
Which merge strategy to choose when doing a notes merge into
12
- refs/notes/<name>. This overrides the more general
13
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in
12
+ `refs/notes/<name>`. This overrides the more general
13
+ `notes.mergeStrategy`. See the "NOTES MERGE STRATEGIES" section in
14
linkgit:git-notes[1] for more information on the available strategies.
15
16
-notes.displayRef::
16
+`notes.displayRef`::
17
Which ref (or refs, if a glob or specified more than once), in
18
addition to the default set by `core.notesRef` or
19
`GIT_NOTES_REF`, to read notes from when showing commit
20
- messages with the 'git log' family of commands.
20
+ messages with the `git log` family of commands.
21
+
22
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
23
environment variable, which must be a colon separated list of refs or
@@ -26,27 +26,27 @@ globs.
26
A warning will be issued for refs that do not exist,
27
but a glob that does not match any refs is silently ignored.
28
+
29
-This setting can be disabled by the `--no-notes` option to the 'git
30
-log' family of commands, or by the `--notes=<ref>` option accepted by
29
+This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1]
30
+family of commands, or by the `--notes=<ref>` option accepted by
31
those commands.
32
+
33
-The effective value of "core.notesRef" (possibly overridden by
34
-GIT_NOTES_REF) is also implicitly added to the list of refs to be
33
+The effective value of `core.notesRef` (possibly overridden by
34
+`GIT_NOTES_REF`) is also implicitly added to the list of refs to be
35
displayed.
36
37
-notes.rewrite.<command>::
38
- When rewriting commits with <command> (currently `amend` or
37
+`notes.rewrite.<command>`::
38
+ When rewriting commits with _<command>_ (currently `amend` or
39
`rebase`), if this variable is `false`, git will not copy
40
notes from the original to the rewritten commit. Defaults to
41
- `true`. See also "`notes.rewriteRef`" below.
41
+ `true`. See also `notes.rewriteRef` below.
42
+
43
This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
44
environment variable, which must be a colon separated list of refs or
45
globs.
46
47
-notes.rewriteMode::
47
+`notes.rewriteMode`::
48
When copying notes during a rewrite (see the
49
- "notes.rewrite.<command>" option), determines what to do if
49
+ `notes.rewrite.<command>` option), determines what to do if
50
the target commit already has a note. Must be one of
51
`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.
52
Defaults to `concatenate`.
@@ -54,7 +54,7 @@ notes.rewriteMode::
54
This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
55
environment variable.
56
57
-notes.rewriteRef::
57
+`notes.rewriteRef`::
58
When copying notes during a rewrite, specifies the (fully
59
qualified) ref whose notes should be copied. May be a glob,
60
in which case notes in all matching refs will be copied. You
Documentation/git-notes.txt
+96
-95
@@ -7,19 +7,19 @@ git-notes - Add or inspect object notes
7
8
SYNOPSIS
9
--------
10
-[verse]
11
-'git notes' [list [<object>]]
12
-'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
13
-'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )
14
-'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
15
-'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]
16
-'git notes' show [<object>]
17
-'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>
18
-'git notes' merge --commit [-v | -q]
19
-'git notes' merge --abort [-v | -q]
20
-'git notes' remove [--ignore-missing] [--stdin] [<object>...]
21
-'git notes' prune [-n] [-v]
22
-'git notes' get-ref
10
+[synopsis]
11
+git notes [list [<object>]]
12
+git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
13
+git notes copy [-f] ( --stdin | <from-object> [<to-object>] )
14
+git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]
15
+git notes edit [--allow-empty] [<object>] [--[no-]stripspace]
16
+git notes show [<object>]
17
+git notes merge [-v | -q] [-s <strategy> ] <notes-ref>
18
+git notes merge --commit [-v | -q]
19
+git notes merge --abort [-v | -q]
20
+git notes remove [--ignore-missing] [--stdin] [<object>...]
21
+git notes prune [-n] [-v]
22
+git notes get-ref
23
24
25
DESCRIPTION
@@ -33,34 +33,34 @@ ENVIRONMENT sections below. If this ref does not exist, it will be
33
quietly created when it is first needed to store a note.
34
35
A typical use of notes is to supplement a commit message without
36
-changing the commit itself. Notes can be shown by 'git log' along with
36
+changing the commit itself. Notes can be shown by `git log` along with
37
the original commit message. To distinguish these notes from the
38
message stored in the commit object, the notes are indented like the
39
-message, after an unindented line saying "Notes (<refname>):" (or
39
+message, after an unindented line saying "Notes (_<refname>_):" (or
40
"Notes:" for `refs/notes/commits`).
41
42
Notes can also be added to patches prepared with `git format-patch` by
43
using the `--notes` option. Such notes are added as a patch commentary
44
after a three dash separator line.
45
46
-To change which notes are shown by 'git log', see the
47
-"notes.displayRef" discussion in <<CONFIGURATION>>.
46
+To change which notes are shown by `git log`, see the
47
+`notes.displayRef` discussion in <<CONFIGURATION,CONFIGURATION>>.
48
49
-See the "notes.rewrite.<command>" configuration for a way to carry
49
+See the `notes.rewrite.<command>` configuration for a way to carry
50
notes across commands that rewrite commits.
51
52
53
SUBCOMMANDS
54
-----------
55
56
-list::
56
+`list`::
57
List the notes object for a given object. If no object is
58
given, show a list of all note objects and the objects they
59
- annotate (in the format "<note-object> <annotated-object>").
59
+ annotate (in the format "`<note-object> <annotated-object>`").
60
This is the default subcommand if no subcommand is given.
61
62
-add::
63
- Add notes for a given object (defaults to HEAD). Abort if the
62
+`add`::
63
+ Add notes for a given object (defaults to `HEAD`). Abort if the
64
object already has notes (use `-f` to overwrite existing notes).
65
However, if you're using `add` interactively (using an editor
66
to supply the notes contents), then - instead of aborting -
@@ -71,10 +71,10 @@ add::
71
fine-tune the message(s) supplied from `-m` and `-F` options
72
interactively (using an editor) before adding the note.
73
74
-copy::
74
+`copy`::
75
Copy the notes for the first object onto the second object (defaults to
76
- HEAD). Abort if the second object already has notes, or if the first
77
- object has none (use -f to overwrite existing notes to the
76
+ `HEAD`). Abort if the second object already has notes, or if the first
77
+ object has none (use `-f` to overwrite existing notes to the
78
second object). This subcommand is equivalent to:
79
`git notes add [-f] -C $(git notes list <from-object>) <to-object>`
80
+
@@ -84,27 +84,27 @@ In `--stdin` mode, take lines in the format
84
<from-object> SP <to-object> [ SP <rest> ] LF
85
----------
86
+
87
-on standard input, and copy the notes from each <from-object> to its
88
-corresponding <to-object>. (The optional `<rest>` is ignored so that
87
+on standard input, and copy the notes from each _<from-object>_ to its
88
+corresponding _<to-object>_. (The optional _<rest>_ is ignored so that
89
the command can read the input given to the `post-rewrite` hook.)
90
91
-append::
91
+`append`::
92
Append new message(s) given by `-m` or `-F` options to an
93
existing note, or add them as a new note if one does not
94
- exist, for the object (defaults to HEAD). When appending to
94
+ exist, for the object (defaults to `HEAD`). When appending to
95
an existing note, a blank line is added before each new
96
message as an inter-paragraph separator. The separator can
97
be customized with the `--separator` option.
98
Edit the notes to be appended given by `-m` and `-F` options with
99
`-e` interactively (using an editor) before appending the note.
100
101
-edit::
102
- Edit the notes for a given object (defaults to HEAD).
101
+`edit`::
102
+ Edit the notes for a given object (defaults to `HEAD`).
103
104
-show::
105
- Show the notes for a given object (defaults to HEAD).
104
+`show`::
105
+ Show the notes for a given object (defaults to `HEAD`).
106
107
-merge::
107
+`merge`::
108
Merge the given notes ref into the current notes ref.
109
This will try to merge the changes made by the given
110
notes ref (called "remote") since the merge-base (if
@@ -112,35 +112,35 @@ merge::
112
+
113
If conflicts arise and a strategy for automatically resolving
114
conflicting notes (see the "NOTES MERGE STRATEGIES" section) is not given,
115
-the "manual" resolver is used. This resolver checks out the
115
+the `manual` resolver is used. This resolver checks out the
116
conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),
117
and instructs the user to manually resolve the conflicts there.
118
When done, the user can either finalize the merge with
119
-'git notes merge --commit', or abort the merge with
120
-'git notes merge --abort'.
119
+`git notes merge --commit`, or abort the merge with
120
+`git notes merge --abort`.
121
122
-remove::
123
- Remove the notes for given objects (defaults to HEAD). When
122
+`remove`::
123
+ Remove the notes for given objects (defaults to `HEAD`). When
124
giving zero or one object from the command line, this is
125
equivalent to specifying an empty note message to
126
the `edit` subcommand.
127
128
-prune::
128
+`prune`::
129
Remove all notes for non-existing/unreachable objects.
130
131
-get-ref::
131
+`get-ref`::
132
Print the current notes ref. This provides an easy way to
133
retrieve the current notes ref (e.g. from scripts).
134
135
OPTIONS
136
-------
137
--f::
138
---force::
137
+`-f`::
138
+`--force`::
139
When adding notes to an object that already has notes,
140
overwrite the existing notes (instead of aborting).
141
142
--m <msg>::
143
---message=<msg>::
142
+`-m <msg>`::
143
+`--message=<msg>`::
144
Use the given note message (instead of prompting).
145
If multiple `-m` options are given, their values
146
are concatenated as separate paragraphs.
@@ -148,95 +148,96 @@ OPTIONS
148
single line between paragraphs will be stripped out.
149
If you wish to keep them verbatim, use `--no-stripspace`.
150
151
--F <file>::
152
---file=<file>::
153
- Take the note message from the given file. Use '-' to
151
+`-F <file>`::
152
+`--file=<file>`::
153
+ Take the note message from the given file. Use `-` to
154
read the note message from the standard input.
155
Lines starting with `#` and empty lines other than a
156
single line between paragraphs will be stripped out.
157
If you wish to keep them verbatim, use `--no-stripspace`.
158
159
--C <object>::
160
---reuse-message=<object>::
159
+`-C <object>`::
160
+`--reuse-message=<object>`::
161
Take the given blob object (for example, another note) as the
162
note message. (Use `git notes copy <object>` instead to
163
copy notes between objects.). By default, message will be
164
copied verbatim, but if you wish to strip out the lines
165
starting with `#` and empty lines other than a single line
166
- between paragraphs, use with`--stripspace` option.
166
+ between paragraphs, use with `--stripspace` option.
167
168
--c <object>::
169
---reedit-message=<object>::
170
- Like '-C', but with `-c` the editor is invoked, so that
168
+`-c <object>`::
169
+`--reedit-message=<object>`::
170
+ Like `-C`, but with `-c` the editor is invoked, so that
171
the user can further edit the note message.
172
173
---allow-empty::
173
+`--allow-empty`::
174
Allow an empty note object to be stored. The default behavior is
175
to automatically remove empty notes.
176
177
---[no-]separator, --separator=<paragraph-break>::
177
+`--[no-]separator`::
178
+`--separator=<paragraph-break>`::
179
Specify a string used as a custom inter-paragraph separator
180
(a newline is added at the end as needed). If `--no-separator`, no
181
separators will be added between paragraphs. Defaults to a blank
182
line.
183
183
---[no-]stripspace::
184
+`--[no-]stripspace`::
185
Strip leading and trailing whitespace from the note message.
186
Also strip out empty lines other than a single line between
187
paragraphs. Lines starting with `#` will be stripped out
188
in non-editor cases like `-m`, `-F` and `-C`, but not in
189
editor case like `git notes edit`, `-c`, etc.
190
190
---ref <ref>::
191
- Manipulate the notes tree in <ref>. This overrides
192
- `GIT_NOTES_REF` and the "core.notesRef" configuration. The ref
191
+`--ref <ref>`::
192
+ Manipulate the notes tree in _<ref>_. This overrides
193
+ `GIT_NOTES_REF` and the `core.notesRef` configuration. The ref
194
specifies the full refname when it begins with `refs/notes/`; when it
195
begins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed
196
to form a full name of the ref.
197
197
---ignore-missing::
198
+`--ignore-missing`::
199
Do not consider it an error to request removing notes from an
200
object that does not have notes attached to it.
201
201
---stdin::
202
+`--stdin`::
203
Also read the object names to remove notes from the standard
204
input (there is no reason you cannot combine this with object
205
names from the command line).
206
206
--n::
207
---dry-run::
207
+`-n`::
208
+`--dry-run`::
209
Do not remove anything; just report the object names whose notes
210
would be removed.
211
211
--s <strategy>::
212
---strategy=<strategy>::
212
+`-s <strategy>`::
213
+`--strategy=<strategy>`::
214
When merging notes, resolve notes conflicts using the given
214
- strategy. The following strategies are recognized: "manual"
215
- (default), "ours", "theirs", "union" and "cat_sort_uniq".
216
- This option overrides the "notes.mergeStrategy" configuration setting.
215
+ strategy. The following strategies are recognized: `manual`
216
+ (default), `ours`, `theirs`, `union` and `cat_sort_uniq`.
217
+ This option overrides the `notes.mergeStrategy` configuration setting.
218
See the "NOTES MERGE STRATEGIES" section below for more
219
information on each notes merge strategy.
220
220
---commit::
221
- Finalize an in-progress 'git notes merge'. Use this option
222
- when you have resolved the conflicts that 'git notes merge'
223
- stored in .git/NOTES_MERGE_WORKTREE. This amends the partial
224
- merge commit created by 'git notes merge' (stored in
225
- .git/NOTES_MERGE_PARTIAL) by adding the notes in
226
- .git/NOTES_MERGE_WORKTREE. The notes ref stored in the
227
- .git/NOTES_MERGE_REF symref is updated to the resulting commit.
228
-
229
---abort::
230
- Abort/reset an in-progress 'git notes merge', i.e. a notes merge
221
+`--commit`::
222
+ Finalize an in-progress `git notes merge`. Use this option
223
+ when you have resolved the conflicts that `git notes merge`
224
+ stored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial
225
+ merge commit created by `git notes merge` (stored in
226
+ `.git/NOTES_MERGE_PARTIAL`) by adding the notes in
227
+ `.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the
228
+ `.git/NOTES_MERGE_REF` symref is updated to the resulting commit.
229
+
230
+`--abort`::
231
+ Abort/reset an in-progress `git notes merge`, i.e. a notes merge
232
with conflicts. This simply removes all files related to the
233
notes merge.
234
234
--q::
235
---quiet::
235
+`-q`::
236
+`--quiet`::
237
When merging notes, operate quietly.
238
238
--v::
239
---verbose::
239
+`-v`::
240
+`--verbose`::
241
When merging notes, be more verbose.
242
When pruning notes, report all object names whose notes are
243
removed.
@@ -270,28 +271,28 @@ object, in which case the history of the notes can be read with
271
NOTES MERGE STRATEGIES
272
----------------------
273
273
-The default notes merge strategy is "manual", which checks out
274
+The default notes merge strategy is `manual`, which checks out
275
conflicting notes in a special work tree for resolving notes conflicts
276
(`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the
277
conflicts in that work tree.
278
When done, the user can either finalize the merge with
278
-'git notes merge --commit', or abort the merge with
279
-'git notes merge --abort'.
279
+`git notes merge --commit`, or abort the merge with
280
+`git notes merge --abort`.
281
282
Users may select an automated merge strategy from among the following using
282
-either -s/--strategy option or configuring notes.mergeStrategy accordingly:
283
+either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly:
284
284
-"ours" automatically resolves conflicting notes in favor of the local
285
+`ours` automatically resolves conflicting notes in favor of the local
286
version (i.e. the current notes ref).
287
287
-"theirs" automatically resolves notes conflicts in favor of the remote
288
+`theirs` automatically resolves notes conflicts in favor of the remote
289
version (i.e. the given notes ref being merged into the current notes
290
ref).
291
291
-"union" automatically resolves notes conflicts by concatenating the
292
+`union` automatically resolves notes conflicts by concatenating the
293
local and remote versions.
294
294
-"cat_sort_uniq" is similar to "union", but in addition to concatenating
295
+`cat_sort_uniq` is similar to `union`, but in addition to concatenating
296
the local and remote versions, this strategy also sorts the resulting
297
lines, and removes duplicate lines from the result. This is equivalent
298
to applying the "cat | sort | uniq" shell pipeline to the local and
@@ -320,7 +321,7 @@ Notes:
321
322
In principle, a note is a regular Git blob, and any kind of
323
(non-)format is accepted. You can binary-safely create notes from
323
-arbitrary files using 'git hash-object':
324
+arbitrary files using `git hash-object`:
325
326
------------
327
$ cc *.c
@@ -331,7 +332,7 @@ $ git notes --ref=built add --allow-empty -C "$blob" HEAD
332
(You cannot simply use `git notes --ref=built add -F a.out HEAD`
333
because that is not binary-safe.)
334
Of course, it doesn't make much sense to display non-text-format notes
334
-with 'git log', so if you use such notes, you'll probably need to write
335
+with `git log`, so if you use such notes, you'll probably need to write
336
some special-purpose tools to do something useful with them.
337
338
@@ -339,7 +340,7 @@ some special-purpose tools to do something useful with them.
340
CONFIGURATION
341
-------------
342
342
-core.notesRef::
343
+`core.notesRef`::
344
Notes ref to read and manipulate instead of
345
`refs/notes/commits`. Must be an unabbreviated ref name.
346
This setting can be overridden through the environment and