{"thread":{"id":"62732","subject":"[PATCH] doc: git-notes.txt: migrate to new documentation format","startedAt":"2025-01-03T17:10:20Z","lastAt":"2025-01-10T10:08:27Z","messageCount":5,"participants":["Jean-Noël Avila via GitGitGadget","Patrick Steinhardt","Junio C Hamano","Jean-Noël AVILA"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"509867","messageId":"pull.1846.git.1735924216993.gitgitgadget@gmail.com","threadId":"62732","inReplyTo":null,"subject":"[PATCH] doc: git-notes.txt: migrate to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-01-03T17:10:16Z","receivedAt":"2025-01-03T17:10:20Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\nThe git-notes manpage files were converted to the new documentation\nformat:\n\n- switching the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- use _<placeholder>_ instead of <placeholder> in the description\n- use `backticks for keywords and more complex option\ndescriptions`. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n    doc: git-notes.txt: migrate to new documentation format\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1846%2Fjnavila%2Fgit-notes-new-format-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1846/jnavila/git-notes-new-format-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1846\n\n Documentation/config/notes.txt |  32 +++---\n Documentation/git-notes.txt    | 193 +++++++++++++++++----------------\n 2 files changed, 113 insertions(+), 112 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex 43db8e808d7..70859f5c574 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -1,4 +1,4 @@\n-notes.mergeStrategy::\n+`notes.mergeStrategy`::\n \tWhich merge strategy to choose by default when resolving notes\n \tconflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`.  Defaults to `manual`.  See the \"NOTES MERGE STRATEGIES\"\n@@ -7,17 +7,17 @@ notes.mergeStrategy::\n This setting can be overridden by passing the `--strategy` option to\n linkgit:git-notes[1].\n \n-notes.<name>.mergeStrategy::\n+`notes.<name>.mergeStrategy`::\n \tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/<name>.  This overrides the more general\n-\t\"notes.mergeStrategy\".  See the \"NOTES MERGE STRATEGIES\" section in\n+\t`refs/notes/<name>`.  This overrides the more general\n+\t`notes.mergeStrategy`.  See the \"NOTES MERGE STRATEGIES\" section in\n \tlinkgit:git-notes[1] for more information on the available strategies.\n \n-notes.displayRef::\n+`notes.displayRef`::\n \tWhich ref (or refs, if a glob or specified more than once), in\n \taddition to the default set by `core.notesRef` or\n \t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n+\tmessages with the `git log` family of commands.\n +\n This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n environment variable, which must be a colon separated list of refs or\n@@ -26,27 +26,27 @@ globs.\n A warning will be issued for refs that do not exist,\n but a glob that does not match any refs is silently ignored.\n +\n-This setting can be disabled by the `--no-notes` option to the 'git\n-log' family of commands, or by the `--notes=<ref>` option accepted by\n+This setting can be disabled by the `--no-notes` option to the `git\n+log` family of commands, or by the `--notes=<ref>` option accepted by\n those commands.\n +\n-The effective value of \"core.notesRef\" (possibly overridden by\n-GIT_NOTES_REF) is also implicitly added to the list of refs to be\n+The effective value of `core.notesRef` (possibly overridden by\n+`GIT_NOTES_REF`) is also implicitly added to the list of refs to be\n displayed.\n \n-notes.rewrite.<command>::\n-\tWhen rewriting commits with <command> (currently `amend` or\n+`notes.rewrite.<command>`::\n+\tWhen rewriting commits with _<command>_ (currently `amend` or\n \t`rebase`), if this variable is `false`, git will not copy\n \tnotes from the original to the rewritten commit.  Defaults to\n-\t`true`.  See also \"`notes.rewriteRef`\" below.\n+\t`true`.  See also `notes.rewriteRef` below.\n +\n This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n \n-notes.rewriteMode::\n+`notes.rewriteMode`::\n \tWhen copying notes during a rewrite (see the\n-\t\"notes.rewrite.<command>\" option), determines what to do if\n+\t`notes.rewrite.<command>` option), determines what to do if\n \tthe target commit already has a note.  Must be one of\n \t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n \tDefaults to `concatenate`.\n@@ -54,7 +54,7 @@ notes.rewriteMode::\n This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n environment variable.\n \n-notes.rewriteRef::\n+`notes.rewriteRef`::\n \tWhen copying notes during a rewrite, specifies the (fully\n \tqualified) ref whose notes should be copied.  May be a glob,\n \tin which case notes in all matching refs will be copied.  You\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 84022f99d76..02a3495986a 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -7,19 +7,19 @@ git-notes - Add or inspect object notes\n \n SYNOPSIS\n --------\n-[verse]\n-'git notes' [list [<object>]]\n-'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n-'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )\n-'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n-'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]\n-'git notes' show [<object>]\n-'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>\n-'git notes' merge --commit [-v | -q]\n-'git notes' merge --abort [-v | -q]\n-'git notes' remove [--ignore-missing] [--stdin] [<object>...]\n-'git notes' prune [-n] [-v]\n-'git notes' get-ref\n+[synopsis]\n+git notes [list [<object>]]\n+git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n+git notes copy [-f] ( --stdin | <from-object> [<to-object>] )\n+git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n+git notes edit [--allow-empty] [<object>] [--[no-]stripspace]\n+git notes show [<object>]\n+git notes merge [-v | -q] [-s <strategy> ] <notes-ref>\n+git notes merge --commit [-v | -q]\n+git notes merge --abort [-v | -q]\n+git notes remove [--ignore-missing] [--stdin] [<object>...]\n+git notes prune [-n] [-v]\n+git notes get-ref\n \n \n DESCRIPTION\n@@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not exist, it will be\n quietly created when it is first needed to store a note.\n \n A typical use of notes is to supplement a commit message without\n-changing the commit itself. Notes can be shown by 'git log' along with\n+changing the commit itself. Notes can be shown by `git log` along with\n the original commit message. To distinguish these notes from the\n message stored in the commit object, the notes are indented like the\n-message, after an unindented line saying \"Notes (<refname>):\" (or\n-\"Notes:\" for `refs/notes/commits`).\n+message, after an unindented line saying \"`Notes (<refname>):`\" (or\n+\"`Notes:`\" for `refs/notes/commits`).\n \n Notes can also be added to patches prepared with `git format-patch` by\n using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n \n-To change which notes are shown by 'git log', see the\n-\"notes.displayRef\" discussion in <<CONFIGURATION>>.\n+To change which notes are shown by `git log`, see the\n+`notes.displayRef` discussion in <<CONFIGURATION,CONFIGURATION>>.\n \n-See the \"notes.rewrite.<command>\" configuration for a way to carry\n+See the `notes.rewrite.<command>` configuration for a way to carry\n notes across commands that rewrite commits.\n \n \n SUBCOMMANDS\n -----------\n \n-list::\n+`list`::\n \tList the notes object for a given object. If no object is\n \tgiven, show a list of all note objects and the objects they\n-\tannotate (in the format \"<note-object> <annotated-object>\").\n+\tannotate (in the format \"`<note-object> <annotated-object>`\").\n \tThis is the default subcommand if no subcommand is given.\n \n-add::\n-\tAdd notes for a given object (defaults to HEAD). Abort if the\n+`add`::\n+\tAdd notes for a given object (defaults to `HEAD`). Abort if the\n \tobject already has notes (use `-f` to overwrite existing notes).\n \tHowever, if you're using `add` interactively (using an editor\n \tto supply the notes contents), then - instead of aborting -\n@@ -71,10 +71,10 @@ add::\n \tfine-tune the message(s) supplied from `-m` and `-F` options\n \tinteractively (using an editor) before adding the note.\n \n-copy::\n+`copy`::\n \tCopy the notes for the first object onto the second object (defaults to\n-\tHEAD). Abort if the second object already has notes, or if the first\n-\tobject has none (use -f to overwrite existing notes to the\n+\t`HEAD`). Abort if the second object already has notes, or if the first\n+\tobject has none (use `-f` to overwrite existing notes to the\n \tsecond object). This subcommand is equivalent to:\n \t`git notes add [-f] -C $(git notes list <from-object>) <to-object>`\n +\n@@ -84,27 +84,27 @@ In `--stdin` mode, take lines in the format\n <from-object> SP <to-object> [ SP <rest> ] LF\n ----------\n +\n-on standard input, and copy the notes from each <from-object> to its\n-corresponding <to-object>.  (The optional `<rest>` is ignored so that\n+on standard input, and copy the notes from each _<from-object>_ to its\n+corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that\n the command can read the input given to the `post-rewrite` hook.)\n \n-append::\n+`append`::\n \tAppend new message(s) given by `-m` or `-F` options to an\n \texisting note, or add them as a new note if one does not\n-\texist, for the object (defaults to HEAD).  When appending to\n+\texist, for the object (defaults to `HEAD`).  When appending to\n \tan existing note, a blank line is added before each new\n \tmessage as an inter-paragraph separator.  The separator can\n \tbe customized with the `--separator` option.\n \tEdit the notes to be appended given by `-m` and `-F` options with\n \t`-e` interactively (using an editor) before appending the note.\n \n-edit::\n-\tEdit the notes for a given object (defaults to HEAD).\n+`edit`::\n+\tEdit the notes for a given object (defaults to `HEAD`).\n \n-show::\n-\tShow the notes for a given object (defaults to HEAD).\n+`show`::\n+\tShow the notes for a given object (defaults to `HEAD`).\n \n-merge::\n+`merge`::\n \tMerge the given notes ref into the current notes ref.\n \tThis will try to merge the changes made by the given\n \tnotes ref (called \"remote\") since the merge-base (if\n@@ -112,35 +112,35 @@ merge::\n +\n If conflicts arise and a strategy for automatically resolving\n conflicting notes (see the \"NOTES MERGE STRATEGIES\" section) is not given,\n-the \"manual\" resolver is used. This resolver checks out the\n+the `manual` resolver is used. This resolver checks out the\n conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),\n and instructs the user to manually resolve the conflicts there.\n When done, the user can either finalize the merge with\n-'git notes merge --commit', or abort the merge with\n-'git notes merge --abort'.\n+`git notes merge --commit`, or abort the merge with\n+`git notes merge --abort`.\n \n-remove::\n-\tRemove the notes for given objects (defaults to HEAD). When\n+`remove`::\n+\tRemove the notes for given objects (defaults to `HEAD`). When\n \tgiving zero or one object from the command line, this is\n \tequivalent to specifying an empty note message to\n \tthe `edit` subcommand.\n \n-prune::\n+`prune`::\n \tRemove all notes for non-existing/unreachable objects.\n \n-get-ref::\n+`get-ref`::\n \tPrint the current notes ref. This provides an easy way to\n \tretrieve the current notes ref (e.g. from scripts).\n \n OPTIONS\n -------\n--f::\n---force::\n+`-f`::\n+`--force`::\n \tWhen adding notes to an object that already has notes,\n \toverwrite the existing notes (instead of aborting).\n \n--m <msg>::\n---message=<msg>::\n+`-m <msg>`::\n+`--message=<msg>`::\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n@@ -148,95 +148,96 @@ OPTIONS\n \tsingle line between paragraphs will be stripped out.\n \tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n--F <file>::\n---file=<file>::\n-\tTake the note message from the given file.  Use '-' to\n+`-F <file>`::\n+`--file=<file>`::\n+\tTake the note message from the given file.  Use `-` to\n \tread the note message from the standard input.\n \tLines starting with `#` and empty lines other than a\n \tsingle line between paragraphs will be stripped out.\n \tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n--C <object>::\n---reuse-message=<object>::\n+`-C <object>`::\n+`--reuse-message=<object>`::\n \tTake the given blob object (for example, another note) as the\n \tnote message. (Use `git notes copy <object>` instead to\n \tcopy notes between objects.).  By default, message will be\n \tcopied verbatim, but if you wish to strip out the lines\n \tstarting with `#` and empty lines other than a single line\n-\tbetween paragraphs, use with`--stripspace` option.\n+\tbetween paragraphs, use with `--stripspace` option.\n \n--c <object>::\n---reedit-message=<object>::\n-\tLike '-C', but with `-c` the editor is invoked, so that\n+`-c <object>`::\n+`--reedit-message=<object>`::\n+\tLike `-C`, but with `-c` the editor is invoked, so that\n \tthe user can further edit the note message.\n \n---allow-empty::\n+`--allow-empty`::\n \tAllow an empty note object to be stored. The default behavior is\n \tto automatically remove empty notes.\n \n---[no-]separator, --separator=<paragraph-break>::\n+`--[no-]separator`::\n+`--separator=<paragraph-break>`::\n \tSpecify a string used as a custom inter-paragraph separator\n \t(a newline is added at the end as needed). If `--no-separator`, no\n \tseparators will be added between paragraphs.  Defaults to a blank\n \tline.\n \n---[no-]stripspace::\n+`--[no-]stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n \tparagraphs. Lines starting with `#` will be stripped out\n \tin non-editor cases like `-m`, `-F` and `-C`, but not in\n \teditor case like `git notes edit`, `-c`, etc.\n \n---ref <ref>::\n-\tManipulate the notes tree in <ref>.  This overrides\n-\t`GIT_NOTES_REF` and the \"core.notesRef\" configuration.  The ref\n+`--ref <ref>`::\n+\tManipulate the notes tree in _<ref>_.  This overrides\n+\t`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref\n \tspecifies the full refname when it begins with `refs/notes/`; when it\n \tbegins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed\n \tto form a full name of the ref.\n \n---ignore-missing::\n+`--ignore-missing`::\n \tDo not consider it an error to request removing notes from an\n \tobject that does not have notes attached to it.\n \n---stdin::\n+`--stdin`::\n \tAlso read the object names to remove notes from the standard\n \tinput (there is no reason you cannot combine this with object\n \tnames from the command line).\n \n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDo not remove anything; just report the object names whose notes\n \twould be removed.\n \n--s <strategy>::\n---strategy=<strategy>::\n+`-s <strategy>`::\n+`--strategy=<strategy>`::\n \tWhen merging notes, resolve notes conflicts using the given\n-\tstrategy. The following strategies are recognized: \"manual\"\n-\t(default), \"ours\", \"theirs\", \"union\" and \"cat_sort_uniq\".\n-\tThis option overrides the \"notes.mergeStrategy\" configuration setting.\n+\tstrategy. The following strategies are recognized: `manual`\n+\t(default), `ours`, `theirs`, `union` and `cat_sort_uniq`.\n+\tThis option overrides the `notes.mergeStrategy` configuration setting.\n \tSee the \"NOTES MERGE STRATEGIES\" section below for more\n \tinformation on each notes merge strategy.\n \n---commit::\n-\tFinalize an in-progress 'git notes merge'. Use this option\n-\twhen you have resolved the conflicts that 'git notes merge'\n-\tstored in .git/NOTES_MERGE_WORKTREE. This amends the partial\n-\tmerge commit created by 'git notes merge' (stored in\n-\t.git/NOTES_MERGE_PARTIAL) by adding the notes in\n-\t.git/NOTES_MERGE_WORKTREE. The notes ref stored in the\n-\t.git/NOTES_MERGE_REF symref is updated to the resulting commit.\n-\n---abort::\n-\tAbort/reset an in-progress 'git notes merge', i.e. a notes merge\n+`--commit`::\n+\tFinalize an in-progress `git notes merge`. Use this option\n+\twhen you have resolved the conflicts that `git notes merge`\n+\tstored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial\n+\tmerge commit created by `git notes merge` (stored in\n+\t`.git/NOTES_MERGE_PARTIAL`) by adding the notes in\n+\t`.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the\n+\t`.git/NOTES_MERGE_REF` symref is updated to the resulting commit.\n+\n+`--abort`::\n+\tAbort/reset an in-progress `git notes merge`, i.e. a notes merge\n \twith conflicts. This simply removes all files related to the\n \tnotes merge.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tWhen merging notes, operate quietly.\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tWhen merging notes, be more verbose.\n \tWhen pruning notes, report all object names whose notes are\n \tremoved.\n@@ -270,28 +271,28 @@ object, in which case the history of the notes can be read with\n NOTES MERGE STRATEGIES\n ----------------------\n \n-The default notes merge strategy is \"manual\", which checks out\n+The default notes merge strategy is `manual`, which checks out\n conflicting notes in a special work tree for resolving notes conflicts\n (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the\n conflicts in that work tree.\n When done, the user can either finalize the merge with\n-'git notes merge --commit', or abort the merge with\n-'git notes merge --abort'.\n+`git notes merge --commit`, or abort the merge with\n+`git notes merge --abort`.\n \n Users may select an automated merge strategy from among the following using\n-either -s/--strategy option or configuring notes.mergeStrategy accordingly:\n+either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly:\n \n-\"ours\" automatically resolves conflicting notes in favor of the local\n+`ours` automatically resolves conflicting notes in favor of the local\n version (i.e. the current notes ref).\n \n-\"theirs\" automatically resolves notes conflicts in favor of the remote\n+`theirs` automatically resolves notes conflicts in favor of the remote\n version (i.e. the given notes ref being merged into the current notes\n ref).\n \n-\"union\" automatically resolves notes conflicts by concatenating the\n+`union` automatically resolves notes conflicts by concatenating the\n local and remote versions.\n \n-\"cat_sort_uniq\" is similar to \"union\", but in addition to concatenating\n+`cat_sort_uniq` is similar to `union`, but in addition to concatenating\n the local and remote versions, this strategy also sorts the resulting\n lines, and removes duplicate lines from the result. This is equivalent\n to applying the \"cat | sort | uniq\" shell pipeline to the local and\n@@ -320,7 +321,7 @@ Notes:\n \n In principle, a note is a regular Git blob, and any kind of\n (non-)format is accepted.  You can binary-safely create notes from\n-arbitrary files using 'git hash-object':\n+arbitrary files using `git hash-object`:\n \n ------------\n $ cc *.c\n@@ -331,7 +332,7 @@ $ git notes --ref=built add --allow-empty -C \"$blob\" HEAD\n (You cannot simply use `git notes --ref=built add -F a.out HEAD`\n because that is not binary-safe.)\n Of course, it doesn't make much sense to display non-text-format notes\n-with 'git log', so if you use such notes, you'll probably need to write\n+with `git log`, so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n \n \n@@ -339,7 +340,7 @@ some special-purpose tools to do something useful with them.\n CONFIGURATION\n -------------\n \n-core.notesRef::\n+`core.notesRef`::\n \tNotes ref to read and manipulate instead of\n \t`refs/notes/commits`.  Must be an unabbreviated ref name.\n \tThis setting can be overridden through the environment and\n\nbase-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694\n-- \ngitgitgadget\n"},{"id":"509950","messageId":"Z3t_GvqfZL9y-_9p@pks.im","threadId":"62732","inReplyTo":"pull.1846.git.1735924216993.gitgitgadget@gmail.com","subject":"Re: [PATCH] doc: git-notes.txt: migrate to new documentation format","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-01-06T07:00:01Z","receivedAt":"2025-01-06T07:00:07Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Jan 03, 2025 at 05:10:16PM +0000, Jean-Noël Avila via GitGitGadget wrote:\n> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> \n> The git-notes manpage files were converted to the new documentation\n> format:\n> \n> - switching the synopsis to a synopsis block which will automatically\n>   format placeholders in italics and keywords in monospace\n> - use _<placeholder>_ instead of <placeholder> in the description\n> - use `backticks for keywords and more complex option\n> descriptions`. The new rendering engine will apply synopsis rules to\n> these spans.\n\nI think it might be a bit easier to send related changes like this and\nyour changes to git-restore(1) in a single patch series going forward.\nIt allows the reviewer to bundle related reviews together, which\nrequires less context switching. It also allows them to more easily\nrefer to similar review feedbacks sent for preceding patches.\n\nOther than that I've got the same comments here regarding the style of\nthe commit message as with your git-restore(1) patch. Ah, I also noticed\nthat the subject should probably be amended because we don't typically\nspecify multiple subsystems with colons. For example:\n\n    Documentation: migrate git-restore(1) to new style format\n\n> diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\n> index 43db8e808d7..70859f5c574 100644\n> --- a/Documentation/config/notes.txt\n> +++ b/Documentation/config/notes.txt\n> @@ -26,27 +26,27 @@ globs.\n>  A warning will be issued for refs that do not exist,\n>  but a glob that does not match any refs is silently ignored.\n>  +\n> -This setting can be disabled by the `--no-notes` option to the 'git\n> -log' family of commands, or by the `--notes=<ref>` option accepted by\n> +This setting can be disabled by the `--no-notes` option to the `git\n> +log` family of commands, or by the `--notes=<ref>` option accepted by\n>  those commands.\n\nShould this rather use \"to the linkgit:git-log[1] family of commands,\n...\"?\n\n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 84022f99d76..02a3495986a 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not exist, it will be\n>  quietly created when it is first needed to store a note.\n>  \n>  A typical use of notes is to supplement a commit message without\n> -changing the commit itself. Notes can be shown by 'git log' along with\n> +changing the commit itself. Notes can be shown by `git log` along with\n>  the original commit message. To distinguish these notes from the\n>  message stored in the commit object, the notes are indented like the\n> -message, after an unindented line saying \"Notes (<refname>):\" (or\n> -\"Notes:\" for `refs/notes/commits`).\n> +message, after an unindented line saying \"`Notes (<refname>):`\" (or\n> +\"`Notes:`\" for `refs/notes/commits`).\n\nCurious. I'm not familiar with the modern best practices around where to\napply what kind of quoting, so why is it \"`foo`\" here and not `\"foo\"` or\n`foo:`?\n\nThanks!\n\nPatrick\n"},{"id":"509996","messageId":"xmqqldvo0xhk.fsf@gitster.g","threadId":"62732","inReplyTo":"Z3t_GvqfZL9y-_9p@pks.im","subject":"Re: [PATCH] doc: git-notes.txt: migrate to new documentation format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-06T15:32:07Z","receivedAt":"2025-01-06T15:32:11Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt <ps@pks.im> writes:\n\n> I think it might be a bit easier to send related changes like this and\n> your changes to git-restore(1) in a single patch series going forward.\n> It allows the reviewer to bundle related reviews together, which\n> requires less context switching. It also allows them to more easily\n> refer to similar review feedbacks sent for preceding patches.\n\nThanks.  I had exactly the same reaction to these patches, and I,\nafter reading all your responses to them, agree with you.\n\n"},{"id":"510123","messageId":"3330199.aeNJFYEL58@cayenne","threadId":"62732","inReplyTo":"Z3t_GvqfZL9y-_9p@pks.im","subject":"Re: [PATCH] doc: git-notes.txt: migrate to new documentation format","fromName":"Jean-Noël AVILA","fromEmail":"jn.avila@free.fr","sentAt":"2025-01-07T21:22:57Z","receivedAt":"2025-01-07T21:23:01Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 6 January 2025 08:00:01 CET Patrick Steinhardt wrote:\n> On Fri, Jan 03, 2025 at 05:10:16PM +0000, Jean-Noël Avila via GitGitGadget \nwrote:\n> > From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n> > \n> > The git-notes manpage files were converted to the new documentation\n> > format:\n> > \n> > - switching the synopsis to a synopsis block which will automatically\n> >   format placeholders in italics and keywords in monospace\n> > - use _<placeholder>_ instead of <placeholder> in the description\n> > - use `backticks for keywords and more complex option\n> > descriptions`. The new rendering engine will apply synopsis rules to\n> > these spans.\n> \n> I think it might be a bit easier to send related changes like this and\n> your changes to git-restore(1) in a single patch series going forward.\n> It allows the reviewer to bundle related reviews together, which\n> requires less context switching. It also allows them to more easily\n> refer to similar review feedbacks sent for preceding patches.\n> \n\nFor simple manpages, I'll do this from now on.\n\n> Other than that I've got the same comments here regarding the style of\n> the commit message as with your git-restore(1) patch. Ah, I also noticed\n> that the subject should probably be amended because we don't typically\n> specify multiple subsystems with colons. For example:\n> \n>     Documentation: migrate git-restore(1) to new style format\n> \n\nWill do.\n\n> > diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\n> > index 43db8e808d7..70859f5c574 100644\n> > --- a/Documentation/config/notes.txt\n> > +++ b/Documentation/config/notes.txt\n> > @@ -26,27 +26,27 @@ globs.\n> >  A warning will be issued for refs that do not exist,\n> >  but a glob that does not match any refs is silently ignored.\n> >  +\n> > -This setting can be disabled by the `--no-notes` option to the 'git\n> > -log' family of commands, or by the `--notes=<ref>` option accepted by\n> > +This setting can be disabled by the `--no-notes` option to the `git\n> > +log` family of commands, or by the `--notes=<ref>` option accepted by\n> >  those commands.\n> \n> Should this rather use \"to the linkgit:git-log[1] family of commands,\n> ...\"?\n> \n\nNice catch, although not really the primary aim of this patch. Will fix.\n\n> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> > index 84022f99d76..02a3495986a 100644\n> > --- a/Documentation/git-notes.txt\n> > +++ b/Documentation/git-notes.txt\n> > @@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not \nexist, it will be\n> >  quietly created when it is first needed to store a note.\n> >  \n> >  A typical use of notes is to supplement a commit message without\n> > -changing the commit itself. Notes can be shown by 'git log' along with\n> > +changing the commit itself. Notes can be shown by `git log` along with\n> >  the original commit message. To distinguish these notes from the\n> >  message stored in the commit object, the notes are indented like the\n> > -message, after an unindented line saying \"Notes (<refname>):\" (or\n> > -\"Notes:\" for `refs/notes/commits`).\n> > +message, after an unindented line saying \"`Notes (<refname>):`\" (or\n> > +\"`Notes:`\" for `refs/notes/commits`).\n> \n> Curious. I'm not familiar with the modern best practices around where to\n> apply what kind of quoting, so why is it \"`foo`\" here and not `\"foo\"` or\n> `foo:`?\n> \n\nGood question. I usually tend to remove double quotes and replace them by back \nquotes when the words are keywords. Here this is a string citation, but I \nwould still prefer to apply the synopsis formatting. Maybe, something lighter \nsuch as \"Notes (_<refname>_):\", which would just format the placeholder, would \nbetter fit.\n\nJN\n\n\n\n"},{"id":"510284","messageId":"pull.1846.v2.git.1736503703573.gitgitgadget@gmail.com","threadId":"62732","inReplyTo":"pull.1846.git.1735924216993.gitgitgadget@gmail.com","subject":"[PATCH v2] doc: convert git-notes to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-01-10T10:08:23Z","receivedAt":"2025-01-10T10:08:27Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>\n\n- Switch the synopsis to a synopsis block which will automatically\n  format placeholders in italics and keywords in monospace\n- Use _<placeholder>_ instead of <placeholder> in the description\n- Use `backticks` for keywords and more complex option\ndescriptions. The new rendering engine will apply synopsis rules to\nthese spans.\n\nSigned-off-by: Jean-Noël Avila <jn.avila@free.fr>\n---\n    doc: git-notes.txt: migrate to new documentation format\n    \n    cc: Patrick Steinhardt ps@pks.im\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1846%2Fjnavila%2Fgit-notes-new-format-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1846/jnavila/git-notes-new-format-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1846\n\nRange-diff vs v1:\n\n 1:  7923846fb09 ! 1:  9c815abd55a doc: git-notes.txt: migrate to new documentation format\n     @@ Metadata\n      Author: Jean-Noël Avila <jn.avila@free.fr>\n      \n       ## Commit message ##\n     -    doc: git-notes.txt: migrate to new documentation format\n     +    doc: convert git-notes to new documentation format\n      \n     -    The git-notes manpage files were converted to the new documentation\n     -    format:\n     -\n     -    - switching the synopsis to a synopsis block which will automatically\n     +    - Switch the synopsis to a synopsis block which will automatically\n            format placeholders in italics and keywords in monospace\n     -    - use _<placeholder>_ instead of <placeholder> in the description\n     -    - use `backticks for keywords and more complex option\n     -    descriptions`. The new rendering engine will apply synopsis rules to\n     +    - Use _<placeholder>_ instead of <placeholder> in the description\n     +    - Use `backticks` for keywords and more complex option\n     +    descriptions. The new rendering engine will apply synopsis rules to\n          these spans.\n      \n          Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>\n     @@ Documentation/config/notes.txt: globs.\n       +\n      -This setting can be disabled by the `--no-notes` option to the 'git\n      -log' family of commands, or by the `--notes=<ref>` option accepted by\n     -+This setting can be disabled by the `--no-notes` option to the `git\n     -+log` family of commands, or by the `--notes=<ref>` option accepted by\n     ++This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1]\n     ++family of commands, or by the `--notes=<ref>` option accepted by\n       those commands.\n       +\n      -The effective value of \"core.notesRef\" (possibly overridden by\n     @@ Documentation/git-notes.txt: ENVIRONMENT sections below.  If this ref does not e\n       the original commit message. To distinguish these notes from the\n       message stored in the commit object, the notes are indented like the\n      -message, after an unindented line saying \"Notes (<refname>):\" (or\n     --\"Notes:\" for `refs/notes/commits`).\n     -+message, after an unindented line saying \"`Notes (<refname>):`\" (or\n     -+\"`Notes:`\" for `refs/notes/commits`).\n     ++message, after an unindented line saying \"Notes (_<refname>_):\" (or\n     + \"Notes:\" for `refs/notes/commits`).\n       \n       Notes can also be added to patches prepared with `git format-patch` by\n       using the `--notes` option. Such notes are added as a patch commentary\n\n\n Documentation/config/notes.txt |  32 +++---\n Documentation/git-notes.txt    | 191 +++++++++++++++++----------------\n 2 files changed, 112 insertions(+), 111 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex 43db8e808d7..b7e536496f5 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -1,4 +1,4 @@\n-notes.mergeStrategy::\n+`notes.mergeStrategy`::\n \tWhich merge strategy to choose by default when resolving notes\n \tconflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`.  Defaults to `manual`.  See the \"NOTES MERGE STRATEGIES\"\n@@ -7,17 +7,17 @@ notes.mergeStrategy::\n This setting can be overridden by passing the `--strategy` option to\n linkgit:git-notes[1].\n \n-notes.<name>.mergeStrategy::\n+`notes.<name>.mergeStrategy`::\n \tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/<name>.  This overrides the more general\n-\t\"notes.mergeStrategy\".  See the \"NOTES MERGE STRATEGIES\" section in\n+\t`refs/notes/<name>`.  This overrides the more general\n+\t`notes.mergeStrategy`.  See the \"NOTES MERGE STRATEGIES\" section in\n \tlinkgit:git-notes[1] for more information on the available strategies.\n \n-notes.displayRef::\n+`notes.displayRef`::\n \tWhich ref (or refs, if a glob or specified more than once), in\n \taddition to the default set by `core.notesRef` or\n \t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n+\tmessages with the `git log` family of commands.\n +\n This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n environment variable, which must be a colon separated list of refs or\n@@ -26,27 +26,27 @@ globs.\n A warning will be issued for refs that do not exist,\n but a glob that does not match any refs is silently ignored.\n +\n-This setting can be disabled by the `--no-notes` option to the 'git\n-log' family of commands, or by the `--notes=<ref>` option accepted by\n+This setting can be disabled by the `--no-notes` option to the linkgit:git-log[1]\n+family of commands, or by the `--notes=<ref>` option accepted by\n those commands.\n +\n-The effective value of \"core.notesRef\" (possibly overridden by\n-GIT_NOTES_REF) is also implicitly added to the list of refs to be\n+The effective value of `core.notesRef` (possibly overridden by\n+`GIT_NOTES_REF`) is also implicitly added to the list of refs to be\n displayed.\n \n-notes.rewrite.<command>::\n-\tWhen rewriting commits with <command> (currently `amend` or\n+`notes.rewrite.<command>`::\n+\tWhen rewriting commits with _<command>_ (currently `amend` or\n \t`rebase`), if this variable is `false`, git will not copy\n \tnotes from the original to the rewritten commit.  Defaults to\n-\t`true`.  See also \"`notes.rewriteRef`\" below.\n+\t`true`.  See also `notes.rewriteRef` below.\n +\n This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n \n-notes.rewriteMode::\n+`notes.rewriteMode`::\n \tWhen copying notes during a rewrite (see the\n-\t\"notes.rewrite.<command>\" option), determines what to do if\n+\t`notes.rewrite.<command>` option), determines what to do if\n \tthe target commit already has a note.  Must be one of\n \t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n \tDefaults to `concatenate`.\n@@ -54,7 +54,7 @@ notes.rewriteMode::\n This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n environment variable.\n \n-notes.rewriteRef::\n+`notes.rewriteRef`::\n \tWhen copying notes during a rewrite, specifies the (fully\n \tqualified) ref whose notes should be copied.  May be a glob,\n \tin which case notes in all matching refs will be copied.  You\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 84022f99d76..5c8e6ff5660 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -7,19 +7,19 @@ git-notes - Add or inspect object notes\n \n SYNOPSIS\n --------\n-[verse]\n-'git notes' [list [<object>]]\n-'git notes' add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n-'git notes' copy [-f] ( --stdin | <from-object> [<to-object>] )\n-'git notes' append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n-'git notes' edit [--allow-empty] [<object>] [--[no-]stripspace]\n-'git notes' show [<object>]\n-'git notes' merge [-v | -q] [-s <strategy> ] <notes-ref>\n-'git notes' merge --commit [-v | -q]\n-'git notes' merge --abort [-v | -q]\n-'git notes' remove [--ignore-missing] [--stdin] [<object>...]\n-'git notes' prune [-n] [-v]\n-'git notes' get-ref\n+[synopsis]\n+git notes [list [<object>]]\n+git notes add [-f] [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n+git notes copy [-f] ( --stdin | <from-object> [<to-object>] )\n+git notes append [--allow-empty] [--[no-]separator | --separator=<paragraph-break>] [--[no-]stripspace] [-F <file> | -m <msg> | (-c | -C) <object>] [-e] [<object>]\n+git notes edit [--allow-empty] [<object>] [--[no-]stripspace]\n+git notes show [<object>]\n+git notes merge [-v | -q] [-s <strategy> ] <notes-ref>\n+git notes merge --commit [-v | -q]\n+git notes merge --abort [-v | -q]\n+git notes remove [--ignore-missing] [--stdin] [<object>...]\n+git notes prune [-n] [-v]\n+git notes get-ref\n \n \n DESCRIPTION\n@@ -33,34 +33,34 @@ ENVIRONMENT sections below.  If this ref does not exist, it will be\n quietly created when it is first needed to store a note.\n \n A typical use of notes is to supplement a commit message without\n-changing the commit itself. Notes can be shown by 'git log' along with\n+changing the commit itself. Notes can be shown by `git log` along with\n the original commit message. To distinguish these notes from the\n message stored in the commit object, the notes are indented like the\n-message, after an unindented line saying \"Notes (<refname>):\" (or\n+message, after an unindented line saying \"Notes (_<refname>_):\" (or\n \"Notes:\" for `refs/notes/commits`).\n \n Notes can also be added to patches prepared with `git format-patch` by\n using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n \n-To change which notes are shown by 'git log', see the\n-\"notes.displayRef\" discussion in <<CONFIGURATION>>.\n+To change which notes are shown by `git log`, see the\n+`notes.displayRef` discussion in <<CONFIGURATION,CONFIGURATION>>.\n \n-See the \"notes.rewrite.<command>\" configuration for a way to carry\n+See the `notes.rewrite.<command>` configuration for a way to carry\n notes across commands that rewrite commits.\n \n \n SUBCOMMANDS\n -----------\n \n-list::\n+`list`::\n \tList the notes object for a given object. If no object is\n \tgiven, show a list of all note objects and the objects they\n-\tannotate (in the format \"<note-object> <annotated-object>\").\n+\tannotate (in the format \"`<note-object> <annotated-object>`\").\n \tThis is the default subcommand if no subcommand is given.\n \n-add::\n-\tAdd notes for a given object (defaults to HEAD). Abort if the\n+`add`::\n+\tAdd notes for a given object (defaults to `HEAD`). Abort if the\n \tobject already has notes (use `-f` to overwrite existing notes).\n \tHowever, if you're using `add` interactively (using an editor\n \tto supply the notes contents), then - instead of aborting -\n@@ -71,10 +71,10 @@ add::\n \tfine-tune the message(s) supplied from `-m` and `-F` options\n \tinteractively (using an editor) before adding the note.\n \n-copy::\n+`copy`::\n \tCopy the notes for the first object onto the second object (defaults to\n-\tHEAD). Abort if the second object already has notes, or if the first\n-\tobject has none (use -f to overwrite existing notes to the\n+\t`HEAD`). Abort if the second object already has notes, or if the first\n+\tobject has none (use `-f` to overwrite existing notes to the\n \tsecond object). This subcommand is equivalent to:\n \t`git notes add [-f] -C $(git notes list <from-object>) <to-object>`\n +\n@@ -84,27 +84,27 @@ In `--stdin` mode, take lines in the format\n <from-object> SP <to-object> [ SP <rest> ] LF\n ----------\n +\n-on standard input, and copy the notes from each <from-object> to its\n-corresponding <to-object>.  (The optional `<rest>` is ignored so that\n+on standard input, and copy the notes from each _<from-object>_ to its\n+corresponding _<to-object>_.  (The optional _<rest>_ is ignored so that\n the command can read the input given to the `post-rewrite` hook.)\n \n-append::\n+`append`::\n \tAppend new message(s) given by `-m` or `-F` options to an\n \texisting note, or add them as a new note if one does not\n-\texist, for the object (defaults to HEAD).  When appending to\n+\texist, for the object (defaults to `HEAD`).  When appending to\n \tan existing note, a blank line is added before each new\n \tmessage as an inter-paragraph separator.  The separator can\n \tbe customized with the `--separator` option.\n \tEdit the notes to be appended given by `-m` and `-F` options with\n \t`-e` interactively (using an editor) before appending the note.\n \n-edit::\n-\tEdit the notes for a given object (defaults to HEAD).\n+`edit`::\n+\tEdit the notes for a given object (defaults to `HEAD`).\n \n-show::\n-\tShow the notes for a given object (defaults to HEAD).\n+`show`::\n+\tShow the notes for a given object (defaults to `HEAD`).\n \n-merge::\n+`merge`::\n \tMerge the given notes ref into the current notes ref.\n \tThis will try to merge the changes made by the given\n \tnotes ref (called \"remote\") since the merge-base (if\n@@ -112,35 +112,35 @@ merge::\n +\n If conflicts arise and a strategy for automatically resolving\n conflicting notes (see the \"NOTES MERGE STRATEGIES\" section) is not given,\n-the \"manual\" resolver is used. This resolver checks out the\n+the `manual` resolver is used. This resolver checks out the\n conflicting notes in a special worktree (`.git/NOTES_MERGE_WORKTREE`),\n and instructs the user to manually resolve the conflicts there.\n When done, the user can either finalize the merge with\n-'git notes merge --commit', or abort the merge with\n-'git notes merge --abort'.\n+`git notes merge --commit`, or abort the merge with\n+`git notes merge --abort`.\n \n-remove::\n-\tRemove the notes for given objects (defaults to HEAD). When\n+`remove`::\n+\tRemove the notes for given objects (defaults to `HEAD`). When\n \tgiving zero or one object from the command line, this is\n \tequivalent to specifying an empty note message to\n \tthe `edit` subcommand.\n \n-prune::\n+`prune`::\n \tRemove all notes for non-existing/unreachable objects.\n \n-get-ref::\n+`get-ref`::\n \tPrint the current notes ref. This provides an easy way to\n \tretrieve the current notes ref (e.g. from scripts).\n \n OPTIONS\n -------\n--f::\n---force::\n+`-f`::\n+`--force`::\n \tWhen adding notes to an object that already has notes,\n \toverwrite the existing notes (instead of aborting).\n \n--m <msg>::\n---message=<msg>::\n+`-m <msg>`::\n+`--message=<msg>`::\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n@@ -148,95 +148,96 @@ OPTIONS\n \tsingle line between paragraphs will be stripped out.\n \tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n--F <file>::\n---file=<file>::\n-\tTake the note message from the given file.  Use '-' to\n+`-F <file>`::\n+`--file=<file>`::\n+\tTake the note message from the given file.  Use `-` to\n \tread the note message from the standard input.\n \tLines starting with `#` and empty lines other than a\n \tsingle line between paragraphs will be stripped out.\n \tIf you wish to keep them verbatim, use `--no-stripspace`.\n \n--C <object>::\n---reuse-message=<object>::\n+`-C <object>`::\n+`--reuse-message=<object>`::\n \tTake the given blob object (for example, another note) as the\n \tnote message. (Use `git notes copy <object>` instead to\n \tcopy notes between objects.).  By default, message will be\n \tcopied verbatim, but if you wish to strip out the lines\n \tstarting with `#` and empty lines other than a single line\n-\tbetween paragraphs, use with`--stripspace` option.\n+\tbetween paragraphs, use with `--stripspace` option.\n \n--c <object>::\n---reedit-message=<object>::\n-\tLike '-C', but with `-c` the editor is invoked, so that\n+`-c <object>`::\n+`--reedit-message=<object>`::\n+\tLike `-C`, but with `-c` the editor is invoked, so that\n \tthe user can further edit the note message.\n \n---allow-empty::\n+`--allow-empty`::\n \tAllow an empty note object to be stored. The default behavior is\n \tto automatically remove empty notes.\n \n---[no-]separator, --separator=<paragraph-break>::\n+`--[no-]separator`::\n+`--separator=<paragraph-break>`::\n \tSpecify a string used as a custom inter-paragraph separator\n \t(a newline is added at the end as needed). If `--no-separator`, no\n \tseparators will be added between paragraphs.  Defaults to a blank\n \tline.\n \n---[no-]stripspace::\n+`--[no-]stripspace`::\n \tStrip leading and trailing whitespace from the note message.\n \tAlso strip out empty lines other than a single line between\n \tparagraphs. Lines starting with `#` will be stripped out\n \tin non-editor cases like `-m`, `-F` and `-C`, but not in\n \teditor case like `git notes edit`, `-c`, etc.\n \n---ref <ref>::\n-\tManipulate the notes tree in <ref>.  This overrides\n-\t`GIT_NOTES_REF` and the \"core.notesRef\" configuration.  The ref\n+`--ref <ref>`::\n+\tManipulate the notes tree in _<ref>_.  This overrides\n+\t`GIT_NOTES_REF` and the `core.notesRef` configuration.  The ref\n \tspecifies the full refname when it begins with `refs/notes/`; when it\n \tbegins with `notes/`, `refs/` and otherwise `refs/notes/` is prefixed\n \tto form a full name of the ref.\n \n---ignore-missing::\n+`--ignore-missing`::\n \tDo not consider it an error to request removing notes from an\n \tobject that does not have notes attached to it.\n \n---stdin::\n+`--stdin`::\n \tAlso read the object names to remove notes from the standard\n \tinput (there is no reason you cannot combine this with object\n \tnames from the command line).\n \n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDo not remove anything; just report the object names whose notes\n \twould be removed.\n \n--s <strategy>::\n---strategy=<strategy>::\n+`-s <strategy>`::\n+`--strategy=<strategy>`::\n \tWhen merging notes, resolve notes conflicts using the given\n-\tstrategy. The following strategies are recognized: \"manual\"\n-\t(default), \"ours\", \"theirs\", \"union\" and \"cat_sort_uniq\".\n-\tThis option overrides the \"notes.mergeStrategy\" configuration setting.\n+\tstrategy. The following strategies are recognized: `manual`\n+\t(default), `ours`, `theirs`, `union` and `cat_sort_uniq`.\n+\tThis option overrides the `notes.mergeStrategy` configuration setting.\n \tSee the \"NOTES MERGE STRATEGIES\" section below for more\n \tinformation on each notes merge strategy.\n \n---commit::\n-\tFinalize an in-progress 'git notes merge'. Use this option\n-\twhen you have resolved the conflicts that 'git notes merge'\n-\tstored in .git/NOTES_MERGE_WORKTREE. This amends the partial\n-\tmerge commit created by 'git notes merge' (stored in\n-\t.git/NOTES_MERGE_PARTIAL) by adding the notes in\n-\t.git/NOTES_MERGE_WORKTREE. The notes ref stored in the\n-\t.git/NOTES_MERGE_REF symref is updated to the resulting commit.\n-\n---abort::\n-\tAbort/reset an in-progress 'git notes merge', i.e. a notes merge\n+`--commit`::\n+\tFinalize an in-progress `git notes merge`. Use this option\n+\twhen you have resolved the conflicts that `git notes merge`\n+\tstored in `.git/NOTES_MERGE_WORKTREE`. This amends the partial\n+\tmerge commit created by `git notes merge` (stored in\n+\t`.git/NOTES_MERGE_PARTIAL`) by adding the notes in\n+\t`.git/NOTES_MERGE_WORKTREE`. The notes ref stored in the\n+\t`.git/NOTES_MERGE_REF` symref is updated to the resulting commit.\n+\n+`--abort`::\n+\tAbort/reset an in-progress `git notes merge`, i.e. a notes merge\n \twith conflicts. This simply removes all files related to the\n \tnotes merge.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tWhen merging notes, operate quietly.\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tWhen merging notes, be more verbose.\n \tWhen pruning notes, report all object names whose notes are\n \tremoved.\n@@ -270,28 +271,28 @@ object, in which case the history of the notes can be read with\n NOTES MERGE STRATEGIES\n ----------------------\n \n-The default notes merge strategy is \"manual\", which checks out\n+The default notes merge strategy is `manual`, which checks out\n conflicting notes in a special work tree for resolving notes conflicts\n (`.git/NOTES_MERGE_WORKTREE`), and instructs the user to resolve the\n conflicts in that work tree.\n When done, the user can either finalize the merge with\n-'git notes merge --commit', or abort the merge with\n-'git notes merge --abort'.\n+`git notes merge --commit`, or abort the merge with\n+`git notes merge --abort`.\n \n Users may select an automated merge strategy from among the following using\n-either -s/--strategy option or configuring notes.mergeStrategy accordingly:\n+either `-s`/`--strategy` option or configuring `notes.mergeStrategy` accordingly:\n \n-\"ours\" automatically resolves conflicting notes in favor of the local\n+`ours` automatically resolves conflicting notes in favor of the local\n version (i.e. the current notes ref).\n \n-\"theirs\" automatically resolves notes conflicts in favor of the remote\n+`theirs` automatically resolves notes conflicts in favor of the remote\n version (i.e. the given notes ref being merged into the current notes\n ref).\n \n-\"union\" automatically resolves notes conflicts by concatenating the\n+`union` automatically resolves notes conflicts by concatenating the\n local and remote versions.\n \n-\"cat_sort_uniq\" is similar to \"union\", but in addition to concatenating\n+`cat_sort_uniq` is similar to `union`, but in addition to concatenating\n the local and remote versions, this strategy also sorts the resulting\n lines, and removes duplicate lines from the result. This is equivalent\n to applying the \"cat | sort | uniq\" shell pipeline to the local and\n@@ -320,7 +321,7 @@ Notes:\n \n In principle, a note is a regular Git blob, and any kind of\n (non-)format is accepted.  You can binary-safely create notes from\n-arbitrary files using 'git hash-object':\n+arbitrary files using `git hash-object`:\n \n ------------\n $ cc *.c\n@@ -331,7 +332,7 @@ $ git notes --ref=built add --allow-empty -C \"$blob\" HEAD\n (You cannot simply use `git notes --ref=built add -F a.out HEAD`\n because that is not binary-safe.)\n Of course, it doesn't make much sense to display non-text-format notes\n-with 'git log', so if you use such notes, you'll probably need to write\n+with `git log`, so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n \n \n@@ -339,7 +340,7 @@ some special-purpose tools to do something useful with them.\n CONFIGURATION\n -------------\n \n-core.notesRef::\n+`core.notesRef`::\n \tNotes ref to read and manipulate instead of\n \t`refs/notes/commits`.  Must be an unabbreviated ref name.\n \tThis setting can be overridden through the environment and\n\nbase-commit: 1b4e9a5f8b5f048972c21fe8acafe0404096f694\n-- \ngitgitgadget\n"}]}