doc: git-notes.txt: migrate to new documentation format
PATCH 1/1 doc: git-notes.txt: migrate to new documentation format
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
The git-notes manpage files were converted to the new documentation format:
- switching 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.
---
doc: git-notes.txt: migrate to new documentation format
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1846%2Fjnavila%2Fgit-notes-new-format-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1846/jnavila/git-notes-new-format-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1846
Documentation/config/notes.txt | 32 +++--- Documentation/git-notes.txt | 193 +++++++++++++++++---------------- 2 files changed, 113 insertions(+), 112 deletions(-)
Documentation/config/notes.txt +16 -16
@@ -1,4 +1,4 @@ -notes.mergeStrategy:: +`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 the "NOTES MERGE STRATEGIES"
@@ -7,17 +7,17 @@ notes.mergeStrategy:: This setting can be overridden by passing the `--strategy` option to linkgit:git-notes[1]. -notes.<name>.mergeStrategy:: +`notes.<name>.mergeStrategy`:: Which merge strategy to choose when doing a notes merge into - refs/notes/<name>. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + `refs/notes/<name>`. This overrides the more general + `notes.mergeStrategy`. See the "NOTES MERGE STRATEGIES" section in linkgit:git-notes[1] for more information on the available strategies. -notes.displayRef:: +`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. + 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
@@ -26,27 +26,27 @@ 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=<ref>` option accepted by +This setting can be disabled by the `--no-notes` option to the `git +log` family of commands, or by the `--notes=<ref>` 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 +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.<command>:: - When rewriting commits with <command> (currently `amend` or +`notes.rewrite.<command>`:: + When rewriting commits with _<command>_ (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. + `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:: +`notes.rewriteMode`:: When copying notes during a rewrite (see the - "notes.rewrite.<command>" option), determines what to do if + `notes.rewrite.<command>` option), determines 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`.
@@ -54,7 +54,7 @@ notes.rewriteMode:: This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. -notes.rewriteRef:: +`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
Documentation/git-notes.txt +97 -96
366 lines not on this page · raw message
base-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694
Signature · 1 line
gitgitgadget
Quoted 11 lines · Jean-Noël Avila via GitGitGadget
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
The git-notes manpage files were converted to the new documentation format:
- switching 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
- usebackticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
I think it might be a bit easier to send related changes like this and your changes to git-restore(1) in a single patch series going forward. It allows the reviewer to bundle related reviews together, which requires less context switching. It also allows them to more easily refer to similar review feedbacks sent for preceding patches.
Other than that I've got the same comments here regarding the style of the commit message as with your git-restore(1) patch. Ah, I also noticed that the subject should probably be amended because we don't typically specify multiple subsystems with colons. For example:
Documentation: migrate git-restore(1) to new style format
Documentation/config/notes.txt globs. · line 31
Quoted 13 lines
Documentation/config/notes.txt +2
-2@@ -26,27 +26,27 @@ 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=<ref>` option accepted by +This setting can be disabled by the `--no-notes` option to the `git +log` family of commands, or by the `--notes=<ref>` option accepted by those commands.
Should this rather use "to the linkgit:git-log[1] family of commands, ..."?
Quoted 6 lines
Documentation/git-notes.txt +0
-0@@ -33,34 +33,34 @@ ENVIRONMENT sections below. If this ref does not exist, it will be quietly created when it is first needed to store a note.
Documentation/git-notes.txt ENVIRONMENT sections below. If this ref does not exist, it will be · line 40
Quoted 10 lines
Documentation/git-notes.txt +3
-3A typical use of notes is to supplement a commit message without -changing the commit itself. Notes can be shown by 'git log' along with +changing the commit itself. Notes can be shown by `git log` along with the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the -message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for `refs/notes/commits`). +message, after an unindented line saying "`Notes (<refname>):`" (or +"`Notes:`" for `refs/notes/commits`).
Curious. I'm not familiar with the modern best practices around where to apply what kind of quoting, so why is it "foo" here and not "foo" or foo:?
Thanks!
Patrick
Quoted 5 lines · Patrick Steinhardt
I think it might be a bit easier to send related changes like this and your changes to git-restore(1) in a single patch series going forward. It allows the reviewer to bundle related reviews together, which requires less context switching. It also allows them to more easily refer to similar review feedbacks sent for preceding patches.
Thanks. I had exactly the same reaction to these patches, and I, after reading all your responses to them, agree with you.
Quoted 1 line · On Monday, 6 January 2025 08:00:01 CET Patrick Steinhardt wrote:
On Fri, Jan 03, 2025 at 05:10:16PM +0000, Jean-Noël Avila via GitGitGadget
Quoted 12 lines · wrote:
Quoted 11 lines
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
The git-notes manpage files were converted to the new documentation format:
- switching 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
- usebackticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
Quoted 6 lines
I think it might be a bit easier to send related changes like this and your changes to git-restore(1) in a single patch series going forward. It allows the reviewer to bundle related reviews together, which requires less context switching. It also allows them to more easily refer to similar review feedbacks sent for preceding patches.
For simple manpages, I'll do this from now on.
Quoted 7 lines
Other than that I've got the same comments here regarding the style of the commit message as with your git-restore(1) patch. Ah, I also noticed that the subject should probably be amended because we don't typically specify multiple subsystems with colons. For example:
Documentation: migrate git-restore(1) to new style format
Will do.
Quoted 8 lines
Quoted 8 lines
Documentation/config/notes.txt +0
-0@@ -26,27 +26,27 @@ globs. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored. +
Quoted 9 lines
Documentation/config/notes.txt globs. · line 31
Quoted 5 lines
Documentation/config/notes.txt +2
-2-This setting can be disabled by the `--no-notes` option to the 'git -log' family of commands, or by the `--notes=<ref>` option accepted by +This setting can be disabled by the `--no-notes` option to the `git +log` family of commands, or by the `--notes=<ref>` option accepted by those commands.Should this rather use "to the linkgit:git-log[1] family of commands, ..."?
Nice catch, although not really the primary aim of this patch. Will fix.
Quoted 5 lines
Documentation/git-notes.txt ENVIRONMENT sections below. If this ref does not
Quoted 5 lines
Documentation/git-notes.txt +0
-0@@ -33,34 +33,34 @@ ENVIRONMENT sections below. If this ref does not
exist, it will be
Quoted 16 lines
Documentation/git-notes.txt ENVIRONMENT sections below. If this ref does not exist, it will be · line 40
Quoted 11 lines
Documentation/git-notes.txt +3
-3quietly created when it is first needed to store a note. A typical use of notes is to supplement a commit message without -changing the commit itself. Notes can be shown by 'git log' along with +changing the commit itself. Notes can be shown by `git log` along with the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the -message, after an unindented line saying "Notes (<refname>):" (or -"Notes:" for `refs/notes/commits`). +message, after an unindented line saying "`Notes (<refname>):`" (or +"`Notes:`" for `refs/notes/commits`).Curious. I'm not familiar with the modern best practices around where to apply what kind of quoting, so why is it "
foo" here and not"foo"orfoo:?
Good question. I usually tend to remove double quotes and replace them by back quotes when the words are keywords. Here this is a string citation, but I would still prefer to apply the synopsis formatting. Maybe, something lighter such as "Notes (_<refname>_):", which would just format the placeholder, would better fit.
JN
PATCH v2 1/1 doc: convert git-notes to new documentation format
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- 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.
---
doc: git-notes.txt: migrate to new documentation format
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1846%2Fjnavila%2Fgit-notes-new-format-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1846/jnavila/git-notes-new-format-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1846
Range-diff vs v1:
1: 7923846fb09 ! 1: 9c815abd55a doc: git-notes.txt: migrate to new documentation format
@@ Metadata
Author: Jean-Noël Avila <[email protected]>
## Commit message ##
- doc: git-notes.txt: migrate to new documentation format
+ doc: convert git-notes to new documentation format
- The git-notes manpage files were converted to the new documentation
- format:
-
- - switching the synopsis to a synopsis block which will automatically
+ - 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
+ - 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.
@@ Documentation/config/notes.txt: globs.
+
-This setting can be disabled by the --no-notes option to the 'git -log' family of commands, or by the --notes=<ref> option accepted by
-+This setting can be disabled by the --no-notes option to the git -+log family of commands, or by the --notes=<ref> option accepted by ++This setting can be disabled by the --no-notes option to the linkgit:git-log[1] ++family of commands, or by the --notes=<ref> option accepted by
those commands.
+
-The effective value of "core.notesRef" (possibly overridden by
@@ Documentation/git-notes.txt: ENVIRONMENT sections below. If this ref does not e
the original commit message. To distinguish these notes from the message stored in the commit object, the notes are indented like the
-message, after an unindented line saying "Notes (<refname>):" (or
--"Notes:" for refs/notes/commits).
-+message, after an unindented line saying "Notes (<refname>):" (or -+"Notes:" for refs/notes/commits).
++message, after an unindented line saying "Notes (_<refname>_):" (or
+ "Notes:" for refs/notes/commits).
Notes can also be added to patches prepared with git format-patch by using the --notes option. Such notes are added as a patch commentary
Documentation/config/notes.txt | 32 +++--- Documentation/git-notes.txt | 191 +++++++++++++++++---------------- 2 files changed, 112 insertions(+), 111 deletions(-)
Documentation/config/notes.txt +16 -16
@@ -1,4 +1,4 @@ -notes.mergeStrategy:: +`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 the "NOTES MERGE STRATEGIES"
@@ -7,17 +7,17 @@ notes.mergeStrategy:: This setting can be overridden by passing the `--strategy` option to linkgit:git-notes[1]. -notes.<name>.mergeStrategy:: +`notes.<name>.mergeStrategy`:: Which merge strategy to choose when doing a notes merge into - refs/notes/<name>. This overrides the more general - "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in + `refs/notes/<name>`. This overrides the more general + `notes.mergeStrategy`. See the "NOTES MERGE STRATEGIES" section in linkgit:git-notes[1] for more information on the available strategies. -notes.displayRef:: +`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. + 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
@@ -26,27 +26,27 @@ 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=<ref>` option accepted by +This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1] +family of commands, or by the `--notes=<ref>` 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 +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.<command>:: - When rewriting commits with <command> (currently `amend` or +`notes.rewrite.<command>`:: + When rewriting commits with _<command>_ (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. + `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:: +`notes.rewriteMode`:: When copying notes during a rewrite (see the - "notes.rewrite.<command>" option), determines what to do if + `notes.rewrite.<command>` option), determines 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`.
@@ -54,7 +54,7 @@ notes.rewriteMode:: This setting can be overridden with the `GIT_NOTES_REWRITE_MODE` environment variable. -notes.rewriteRef:: +`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
Documentation/git-notes.txt +96 -95
365 lines not on this page · raw message
base-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694
Signature · 1 line
gitgitgadget