From 5bd277e2e2059840cda807de511f02c291e039c9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Wed, 7 Sep 2022 10:27:01 +0200 Subject: [PATCH] notes docs: de-duplicate and combine configuration sections MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Matheus Tavares Signed-off-by: Junio C Hamano --- Documentation/config/notes.txt | 43 ++++++++++++++++++++------------- Documentation/git-log.txt | 16 +++--------- Documentation/git-notes.txt | 55 +++--------------------------------------- 3 files changed, 33 insertions(+), 81 deletions(-) diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt index aeef56d49a..c7c4811734 100644 --- a/Documentation/config/notes.txt +++ b/Documentation/config/notes.txt @@ -3,6 +3,9 @@ notes.mergeStrategy:: conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" section of linkgit:git-notes[1] for more information on each strategy. ++ +This setting can be overridden by passing the `--strategy` option to +linkgit:git-notes[1]. notes..mergeStrategy:: Which merge strategy to choose when doing a notes merge into @@ -11,28 +14,35 @@ notes..mergeStrategy:: linkgit:git-notes[1] for more information on the available strategies. notes.displayRef:: - The (fully qualified) refname from which to show notes when - showing commit messages. The value of this variable can be set - to a glob, in which case notes from all matching refs will be - shown. You may also specify this configuration variable - several times. A warning will be issued for refs that do not - exist, but a glob that does not match any refs is silently - ignored. + Which ref (or refs, if a glob or specified more than once), in + addition to the default set by `core.notesRef` or + `GIT_NOTES_REF`, to read notes from when showing commit + messages with the 'git log' family of commands. + This setting can be overridden with the `GIT_NOTES_DISPLAY_REF` environment variable, which must be a colon separated list of refs or globs. + +A warning will be issued for refs that do not exist, +but a glob that does not match any refs is silently ignored. ++ +This setting can be disabled by the `--no-notes` option to the 'git +log' family of commands, or by the `--notes=` option accepted by +those commands. ++ The effective value of "core.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed. notes.rewrite.:: When rewriting commits with (currently `amend` or - `rebase`) and this variable is set to `true`, Git - automatically copies your notes from the original to the - rewritten commit. Defaults to `true`, but see - "notes.rewriteRef" below. + `rebase`), if this variable is `false`, git will not copy + notes from the original to the rewritten commit. Defaults to + `true`. See also "`notes.rewriteRef`" below. ++ +This setting can be overridden with the `GIT_NOTES_REWRITE_REF` +environment variable, which must be a colon separated list of refs or +globs. notes.rewriteMode:: When copying notes during a rewrite (see the @@ -46,14 +56,13 @@ environment variable. notes.rewriteRef:: When copying notes during a rewrite, specifies the (fully - qualified) ref whose notes should be copied. The ref may be a - glob, in which case notes in all matching refs will be copied. - You may also specify this configuration several times. + qualified) ref whose notes should be copied. May be a glob, + in which case notes in all matching refs will be copied. You + may also specify this configuration several times. + Does not have a default value; you must configure this variable to enable note rewriting. Set it to `refs/notes/commits` to enable rewriting for the default commit notes. + -This setting can be overridden with the `GIT_NOTES_REWRITE_REF` -environment variable, which must be a colon separated list of refs or -globs. +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. +See `notes.rewrite.` above for a further description of its format. diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 20e87cecf4..ed802bb8e1 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -227,19 +227,9 @@ log.showSignature:: mailmap.*:: See linkgit:git-shortlog[1]. -notes.displayRef:: - Which refs, in addition to the default set by `core.notesRef` - or `GIT_NOTES_REF`, to read notes from when showing commit - messages with the `log` family of commands. See - linkgit:git-notes[1]. -+ -May be an unabbreviated ref name or a glob and may be specified -multiple times. A warning will be issued for refs that do not exist, -but a glob that does not match any refs is silently ignored. -+ -This setting can be disabled by the `--no-notes` option, -overridden by the `GIT_NOTES_DISPLAY_REF` environment variable, -and overridden by the `--notes=` option. +include::includes/cmd-config-section-rest.txt[] + +include::config/notes.txt[] GIT --- diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt index 0a4200674c..efbc10f0f5 100644 --- a/Documentation/git-notes.txt +++ b/Documentation/git-notes.txt @@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary after a three dash separator line. To change which notes are shown by 'git log', see the -"notes.displayRef" configuration in linkgit:git-log[1]. +"notes.displayRef" discussion in <>. See the "notes.rewrite." configuration for a way to carry 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 some special-purpose tools to do something useful with them. +[[CONFIGURATION]] CONFIGURATION ------------- @@ -316,57 +317,9 @@ core.notesRef:: This setting can be overridden through the environment and command line. -notes.mergeStrategy:: - Which merge strategy to choose by default when resolving notes - conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or - `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES" - section above for more information on each strategy. -+ -This setting can be overridden by passing the `--strategy` option. - -notes..mergeStrategy:: - Which merge strategy to choose when doing a notes merge into - refs/notes/. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above - for more information on each available strategy. - -notes.displayRef:: - Which ref (or refs, if a glob or specified more than once), in - addition to the default set by `core.notesRef` or - `GIT_NOTES_REF`, to read notes from when showing commit - messages with the 'git log' family of commands. - This setting can be overridden on the command line or by the - `GIT_NOTES_DISPLAY_REF` environment variable. - See linkgit:git-log[1]. - -notes.rewrite.:: - When rewriting commits with (currently `amend` or - `rebase`), if this variable is `false`, git will not copy - notes from the original to the rewritten commit. Defaults to - `true`. See also "`notes.rewriteRef`" below. -+ -This setting can be overridden by the `GIT_NOTES_REWRITE_REF` -environment variable. +include::includes/cmd-config-section-rest.txt[] -notes.rewriteMode:: - When copying notes during a rewrite, what to do if the target - commit already has a note. Must be one of `overwrite`, - `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to - `concatenate`. -+ -This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` -environment variable. - -notes.rewriteRef:: - When copying notes during a rewrite, specifies the (fully - qualified) ref whose notes should be copied. May be a glob, - in which case notes in all matching refs will be copied. You - may also specify this configuration several times. -+ -Does not have a default value; you must configure this variable to -enable note rewriting. -+ -Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable. +include::config/notes.txt[] ENVIRONMENT -- 2.11.4.GIT