notes docs: de-duplicate and combine configuration sections
Combine the various "notes" configuration sections spread across Documentation/config/notes.txt and Documentation/git-notes.txt to live in the former, and to be included in the latter. We'll now forward link from "git notes" to the "CONFIGURATION" section below, rather than to "git-config(1)" when discussing configuration variables that are (also) discussed in that section. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Reviewed-by: Matheus Tavares <matheus.bernardino@usp.br> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Sep 7, 2022 at 10:27 UTC
5bd277e2e2059840cda807de511f02c291e039c9
3 files changed
+33
-81
Documentation/config/notes.txt
+26
-17
@@ -3,6 +3,9 @@ notes.mergeStrategy::
3
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
4
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
5
section of linkgit:git-notes[1] for more information on each strategy.
6
++
7
+This setting can be overridden by passing the `--strategy` option to
8
+linkgit:git-notes[1].
9
10
notes.<name>.mergeStrategy::
11
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
14
linkgit:git-notes[1] for more information on the available strategies.
15
16
notes.displayRef::
14
- The (fully qualified) refname from which to show notes when
15
- showing commit messages. The value of this variable can be set
16
- to a glob, in which case notes from all matching refs will be
17
- shown. You may also specify this configuration variable
18
- several times. A warning will be issued for refs that do not
19
- exist, but a glob that does not match any refs is silently
20
- ignored.
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.
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
24
globs.
25
+
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
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
35
displayed.
36
37
notes.rewrite.<command>::
38
When rewriting commits with <command> (currently `amend` or
32
- `rebase`) and this variable is set to `true`, Git
33
- automatically copies your notes from the original to the
34
- rewritten commit. Defaults to `true`, but see
35
- "notes.rewriteRef" below.
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.
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::
48
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
56
57
notes.rewriteRef::
58
When copying notes during a rewrite, specifies the (fully
49
- qualified) ref whose notes should be copied. The ref may be a
50
- glob, in which case notes in all matching refs will be copied.
51
- You may also specify this configuration several times.
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
61
+ may also specify this configuration several times.
62
+
63
Does not have a default value; you must configure this variable to
64
enable note rewriting. Set it to `refs/notes/commits` to enable
65
rewriting for the default commit notes.
66
+
57
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
58
-environment variable, which must be a colon separated list of refs or
59
-globs.
67
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
68
+See `notes.rewrite.<command>` above for a further description of its format.
Documentation/git-log.txt
+3
-13
@@ -227,19 +227,9 @@ log.showSignature::
227
mailmap.*::
228
See linkgit:git-shortlog[1].
229
230
-notes.displayRef::
231
- Which refs, in addition to the default set by `core.notesRef`
232
- or `GIT_NOTES_REF`, to read notes from when showing commit
233
- messages with the `log` family of commands. See
234
- linkgit:git-notes[1].
235
-+
236
-May be an unabbreviated ref name or a glob and may be specified
237
-multiple times. A warning will be issued for refs that do not exist,
238
-but a glob that does not match any refs is silently ignored.
239
-+
240
-This setting can be disabled by the `--no-notes` option,
241
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
242
-and overridden by the `--notes=<ref>` option.
230
+include::includes/cmd-config-section-rest.txt[]
231
+
232
+include::config/notes.txt[]
233
234
GIT
235
---
Documentation/git-notes.txt
+4
-51
@@ -44,7 +44,7 @@ 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" configuration in linkgit:git-log[1].
47
+"notes.displayRef" discussion in <<CONFIGURATION>>.
48
49
See the "notes.rewrite.<command>" configuration for a way to carry
50
notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
307
some special-purpose tools to do something useful with them.
308
309
310
+[[CONFIGURATION]]
311
CONFIGURATION
312
-------------
313
@@ -316,57 +317,9 @@ core.notesRef::
317
This setting can be overridden through the environment and
318
command line.
319
319
-notes.mergeStrategy::
320
- Which merge strategy to choose by default when resolving notes
321
- conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
322
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
323
- section above for more information on each strategy.
324
-+
325
-This setting can be overridden by passing the `--strategy` option.
326
-
327
-notes.<name>.mergeStrategy::
328
- Which merge strategy to choose when doing a notes merge into
329
- refs/notes/<name>. This overrides the more general
330
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
331
- for more information on each available strategy.
332
-
333
-notes.displayRef::
334
- Which ref (or refs, if a glob or specified more than once), in
335
- addition to the default set by `core.notesRef` or
336
- `GIT_NOTES_REF`, to read notes from when showing commit
337
- messages with the 'git log' family of commands.
338
- This setting can be overridden on the command line or by the
339
- `GIT_NOTES_DISPLAY_REF` environment variable.
340
- See linkgit:git-log[1].
341
-
342
-notes.rewrite.<command>::
343
- When rewriting commits with <command> (currently `amend` or
344
- `rebase`), if this variable is `false`, git will not copy
345
- notes from the original to the rewritten commit. Defaults to
346
- `true`. See also "`notes.rewriteRef`" below.
347
-+
348
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
349
-environment variable.
320
+include::includes/cmd-config-section-rest.txt[]
321
351
-notes.rewriteMode::
352
- When copying notes during a rewrite, what to do if the target
353
- commit already has a note. Must be one of `overwrite`,
354
- `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
355
- `concatenate`.
356
-+
357
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
358
-environment variable.
359
-
360
-notes.rewriteRef::
361
- When copying notes during a rewrite, specifies the (fully
362
- qualified) ref whose notes should be copied. May be a glob,
363
- in which case notes in all matching refs will be copied. You
364
- may also specify this configuration several times.
365
-+
366
-Does not have a default value; you must configure this variable to
367
-enable note rewriting.
368
-+
369
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
322
+include::config/notes.txt[]
323
324
325
ENVIRONMENT