{"thread":{"id":"63218","subject":"[PATCH 0/5] doc: convert git-reset, git-rm and git-mv to new documentation format","startedAt":"2025-03-30T17:16:07Z","lastAt":"2025-04-14T21:47:35Z","messageCount":19,"participants":["Jean-Noël Avila via GitGitGadget","Martin Ågren","Jean-Noël Avila","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":5},"messages":[{"id":"515302","messageId":"pull.1896.git.1743354964.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":null,"subject":"[PATCH 0/5] doc: convert git-reset, git-rm and git-mv to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:15:59Z","receivedAt":"2025-03-30T17:16:07Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":" * Switch the synopsis to a synopsis block which will automatically format\n placeholders in italics and keywords in monospace\n * Use instead of in the description\n * Use backticks for keywords and more complex option descriptions. The new\n rendering engine will apply synopsis rules to these spans.\n\nJean-Noël Avila (5):\n doc: convert git-reset to new documentation format\n doc: fix synopsis analysis logic\n doc: convert git-rm to new documentation format\n doc: move synopsis git-mv commands in the synopsis section\n doc: convert git-mv to new documentation format\n\n Documentation/asciidoc.conf.in | 8 +-\n Documentation/asciidoctor-extensions.rb.in | 6 +-\n Documentation/git-mv.adoc | 33 ++++---\n Documentation/git-reset.adoc | 100 ++++++++++-----------\n Documentation/git-rm.adoc | 56 ++++++------\n builtin/mv.c | 3 +-\n 6 files changed, 103 insertions(+), 103 deletions(-)\n\n\nbase-commit: 66b90d9bad8476f6f3d71f5add5cf78809a998ed\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1896%2Fjnavila%2Fdoc_git_reset-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1896/jnavila/doc_git_reset-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1896\n-- \ngitgitgadget\n"},{"id":"515303","messageId":"1676b5ac628fd2898c3dab1b25d6a852cedfa6ae.1743354964.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH 1/5] doc: convert git-reset to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:16:00Z","receivedAt":"2025-03-30T17:16:09Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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 \n---\n Documentation/git-reset.adoc | 100 +++++++++++++++++------------------\n 1 file changed, 50 insertions(+), 50 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 79ad5643eed..5c73448e072 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state\n \n SYNOPSIS\n --------\n-[verse]\n-'git reset' [-q] [] [--] ...\n-'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n-'git reset' (--patch | -p) [] [--] [...]\n-'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n+[synopsis]\n+git reset [-q] [] [--] ...\n+git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n+git reset (--patch | -p) [] [--] [...]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from `` to the index.\n-In the last form, set the current branch head (`HEAD`) to ``,\n+In the first three forms, copy entries from __ to the index.\n+In the last form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n-The ``/`` defaults to `HEAD` in all forms.\n+The __/__ defaults to `HEAD` in all forms.\n \n-'git reset' [-q] [] [--] ...::\n-'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] []::\n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n \tThese forms reset the index entries for all paths that match the\n-\t`` to their state at ``. (It does not affect\n+\t__ to their state at __. (It does not affect\n \tthe working tree or the current branch.)\n +\n This means that `git reset ` is the opposite of `git add\n@@ -37,30 +37,30 @@ and specifying a commit with `--source`, you\n can copy the contents of a path out of a commit to the index and to the\n working tree in one go.\n \n-'git reset' (--patch | -p) [] [--] [...]::\n+`git reset (--patch | -p) [] [--] [...]`::\n \tInteractively select hunks in the difference between the index\n-\tand `` (defaults to `HEAD`). The chosen hunks are applied\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n \tin reverse to the index.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the ``Interactive Mode''\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n \n-'git reset' [] []::\n-\tThis form resets the current branch head to `` and\n-\tpossibly updates the index (resetting it to the tree of ``) and\n-\tthe working tree depending on ``. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If `` is omitted,\n-\tdefaults to `--mixed`. The `` must be one of the following:\n+`git reset [] []`::\n+\tThis form resets the current branch head to __ and\n+\tpossibly updates the index (resetting it to the tree of __) and\n+\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n+\tis set to the tip of the current branch. If __ is omitted,\n+\tdefaults to `--mixed`. The __ must be one of the following:\n +\n --\n---soft::\n+`--soft`::\n \tDoes not touch the index file or the working tree at all (but\n-\tresets the head to ``, just like all modes do). This leaves\n-\tall your changed files \"Changes to be committed\", as `git status`\n+\tresets the head to __, just like all modes do). This leaves\n+\tall your changed files \"Changes to be committed\", as `git status\n \twould put it.\n \n---mixed::\n+`--mixed`::\n \tResets the index but not the working tree (i.e., the changed files\n \tare preserved but not marked for commit) and reports what has not\n \tbeen updated. This is the default action.\n@@ -68,33 +68,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n If `-N` is specified, removed paths are marked as intent-to-add (see\n linkgit:git-add[1]).\n \n---hard::\n+`--hard`::\n \tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since `` are discarded. Any untracked files or\n+\tworking tree since __ are discarded. Any untracked files or\n \tdirectories in the way of writing any tracked files are simply deleted.\n \n---merge::\n+`--merge`::\n \tResets the index and updates the files in the working tree that are\n-\tdifferent between `` and `HEAD`, but keeps those which are\n+\tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n-\tIf a file that is different between `` and the index has\n+\tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n +\n In other words, `--merge` does something like a `git read-tree -u -m `,\n but carries forward unmerged index entries.\n \n---keep::\n+`--keep`::\n \tResets index entries and updates files in the working tree that are\n-\tdifferent between `` and `HEAD`.\n-\tIf a file that is different between `` and `HEAD` has local\n+\tdifferent between __ and `HEAD`.\n+\tIf a file that is different between __ and `HEAD` has local\n \tchanges, reset is aborted.\n \n---[no-]recurse-submodules::\n-\tWhen the working tree is updated, using --recurse-submodules will\n+`--[no-]recurse-submodules`::\n+\tWhen the working tree is updated, using `--recurse-submodules` will\n \talso recursively reset the working tree of all active submodules\n \taccording to the commit recorded in the superproject, also setting\n-\tthe submodules' HEAD to be detached at that commit.\n+\tthe submodules' `HEAD` to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n@@ -104,31 +104,31 @@ between the three commands.\n OPTIONS\n -------\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet, only report errors.\n \n---refresh::\n---no-refresh::\n+`--refresh`::\n+`--no-refresh`::\n \tRefresh the index after a mixed reset. Enabled by default.\n \n---pathspec-from-file=::\n-\tPathspec is passed in `` instead of commandline args. If\n-\t`` is exactly `-` then standard input is used. Pathspec\n-\telements are separated by LF or CR/LF. Pathspec elements can be\n+`--pathspec-from-file=`::\n+\tPathspec is passed in __ instead of commandline args. If\n+\t__ is exactly `-` then standard input is used. Pathspec\n+\telements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n \tglobal `--literal-pathspecs`.\n \n---pathspec-file-nul::\n+`--pathspec-file-nul`::\n \tOnly meaningful with `--pathspec-from-file`. Pathspec elements are\n-\tseparated with NUL character and all other characters are taken\n+\tseparated with _NUL_ character and all other characters are taken\n \tliterally (including newlines and quotes).\n \n-\\--::\n+`--`::\n \tDo not interpret any more arguments as options.\n \n-...::\n+`...`::\n \tLimits the paths affected by the operation.\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n@@ -348,7 +348,7 @@ $ git commit ... <8>\n ------------\n +\n <1> First, reset the history back one commit so that we remove the original\n- commit, but leave the working tree with all the changes. The -N ensures\n+ commit, but leave the working tree with all the changes. The `-N` ensures\n that any new files added with `HEAD` are still marked so that `git add -p`\n will find them.\n <2> Next, we interactively select diff hunks to add using the `git add -p`\n@@ -458,7 +458,7 @@ working index HEAD target working index HEAD\n \t\t\t --keep B C C\n ....\n \n-`reset --merge` is meant to be used when resetting out of a conflicted\n+`git reset --merge` is meant to be used when resetting out of a conflicted\n merge. Any mergy operation guarantees that the working tree file that is\n involved in the merge does not have a local change with respect to the index\n before it starts, and that it writes the result out to the working tree. So if\n@@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not\n resetting out from a state that a mergy operation left after failing\n with a conflict. That is why we disallow `--merge` option in this case.\n \n-`reset --keep` is meant to be used when removing some of the last\n+`git reset --keep` is meant to be used when removing some of the last\n commits in the current branch while keeping changes in the working\n tree. If there could be conflicts between the changes in the commit we\n want to remove and the changes in the working tree we want to keep,\n-- \ngitgitgadget\n\n"},{"id":"515304","messageId":"6206e65ac4d50e174ad7e3dbafaa590b632f214b.1743354964.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH 2/5] doc: fix synopsis analysis logic","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:16:01Z","receivedAt":"2025-03-30T17:16:09Z","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?= \n\nThe synopsis analysis logic was not able to handle backslashes and stars\nwhich are used in the synopsis of the git-rm command. This patch fixes the\nissue by updating the regular expression used to match the keywords.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/asciidoc.conf.in | 8 ++++----\n Documentation/asciidoctor-extensions.rb.in | 6 +++---\n 2 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex f2aef6cb79f..50f0e81a831 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -43,7 +43,7 @@ ifdef::doctype-book[]\n endif::doctype-book[]\n \n [literal-inlinemacro]\n-{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\\\\\*\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n \n endif::backend-docbook[]\n \n@@ -75,18 +75,18 @@ git-relative-html-prefix=\n {target}{0?({0})}\n \n [literal-inlinemacro]\n-{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\\\\\*\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n \n endif::backend-xhtml11[]\n \n ifdef::backend-docbook[]\n ifdef::doctype-manpage[]\n [paradef-default]\n-synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::doctype-manpage[]\n endif::backend-docbook[]\n \n ifdef::backend-xhtml11[]\n [paradef-default]\n-synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\nindex 2494f17a514..09156b71a4f 100644\n--- a/Documentation/asciidoctor-extensions.rb.in\n+++ b/Documentation/asciidoctor-extensions.rb.in\n@@ -50,7 +50,7 @@ module Git\n def process parent, reader, attrs\n outlines = reader.lines.map do |l|\n l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n- .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n+ .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+)}, '\\1{empty}`\\2`{empty}')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n .gsub(']', ']{empty}')\n end\n@@ -72,7 +72,7 @@ module Git\n %()\n elsif type == :monospaced\n node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n- .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n+ .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n else\n open, close, supports_phrase = QUOTE_TAGS[type]\n@@ -100,7 +100,7 @@ module Git\n def convert_inline_quoted node\n if node.type == :monospaced\n node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n- .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n+ .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n \n else\n-- \ngitgitgadget\n\n"},{"id":"515305","messageId":"41a01969d9394ba4997e729d58c5b566bab315b7.1743354964.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH 3/5] doc: convert git-rm to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:16:02Z","receivedAt":"2025-03-30T17:16:10Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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 \n---\n Documentation/git-rm.adoc | 56 +++++++++++++++++++--------------------\n 1 file changed, 28 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc\nindex 363a26934f5..b5ead867963 100644\n--- a/Documentation/git-rm.adoc\n+++ b/Documentation/git-rm.adoc\n@@ -7,10 +7,10 @@ git-rm - Remove files from the working tree and from the index\n \n SYNOPSIS\n --------\n-[verse]\n-'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n-\t [--quiet] [--pathspec-from-file= [--pathspec-file-nul]]\n-\t [--] [...]\n+[synopsis]\n+git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n+ [--quiet] [--pathspec-from-file= [--pathspec-file-nul]]\n+ [--] [...]\n \n DESCRIPTION\n -----------\n@@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]),\n \n OPTIONS\n -------\n-...::\n+`...`::\n \tFiles to remove. A leading directory name (e.g. `dir` to remove\n \t`dir/file1` and `dir/file2`) can be given to remove all files in\n \tthe directory, and recursively all sub-directories, but this\n@@ -43,57 +43,57 @@ directories `d` and `d2`, there is a difference between using\n `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all\n of directory `d2`.\n +\n-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n+For more details, see the __ entry in linkgit:gitglossary[7].\n \n--f::\n---force::\n+`-f`::\n+`--force`::\n \tOverride the up-to-date check.\n \n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDon't actually remove any file(s). Instead, just show\n \tif they exist in the index and would otherwise be removed\n \tby the command.\n \n--r::\n+`-r`::\n Allow recursive removal when a leading directory name is\n given.\n \n-\\--::\n+`--`::\n \tThis option can be used to separate command-line options from\n \tthe list of files, (useful when filenames might be mistaken\n \tfor command-line options).\n \n---cached::\n+`--cached`::\n \tUse this option to unstage and remove paths only from the index.\n \tWorking tree files, whether modified or not, will be\n \tleft alone.\n \n---ignore-unmatch::\n+`--ignore-unmatch`::\n \tExit with a zero status even if no files matched.\n \n---sparse::\n+`--sparse`::\n \tAllow updating index entries outside of the sparse-checkout cone.\n \tNormally, `git rm` refuses to update index entries whose paths do\n \tnot fit within the sparse-checkout cone. See\n \tlinkgit:git-sparse-checkout[1] for more.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \t`git rm` normally outputs one line (in the form of an `rm` command)\n \tfor each file removed. This option suppresses that output.\n \n---pathspec-from-file=::\n-\tPathspec is passed in `` instead of commandline args. If\n-\t`` is exactly `-` then standard input is used. Pathspec\n-\telements are separated by LF or CR/LF. Pathspec elements can be\n+`--pathspec-from-file=`::\n+\tPathspec is passed in __ instead of args. If\n+\t__ is exactly `-` then standard input is used. Pathspec\n+\telements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n \tglobal `--literal-pathspecs`.\n \n---pathspec-file-nul::\n+`--pathspec-file-nul`::\n \tOnly meaningful with `--pathspec-from-file`. Pathspec elements are\n-\tseparated with NUL character and all other characters are taken\n+\tseparated with _NUL_ character and all other characters are taken\n \tliterally (including newlines and quotes).\n \n \n@@ -153,15 +153,15 @@ SUBMODULES\n ----------\n Only submodules using a gitfile (which means they were cloned\n with a Git version 1.7.8 or newer) will be removed from the work\n-tree, as their repository lives inside the .git directory of the\n+tree, as their repository lives inside the `.git` directory of the\n superproject. If a submodule (or one of those nested inside it)\n-still uses a .git directory, `git rm` will move the submodules\n+still uses a `.git` directory, `git rm` moves the submodules\n git directory into the superprojects git directory to protect\n-the submodule's history. If it exists the submodule. section\n+the submodule's history. If it exists the `submodule.` section\n in the linkgit:gitmodules[5] file will also be removed and that file\n-will be staged (unless --cached or -n are used).\n+will be staged (unless `--cached` or `-n` are used).\n \n-A submodule is considered up to date when the HEAD is the same as\n+A submodule is considered up to date when the `HEAD` is the same as\n recorded in the index, no tracked files are modified and no untracked\n files that aren't ignored are present in the submodule's work tree.\n Ignored files are deemed expendable and won't stop a submodule's work\n-- \ngitgitgadget\n\n"},{"id":"515306","messageId":"9f7cd02cc1ef76bfe92cbb8152f34460c67b2eda.1743354964.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH 4/5] doc: move synopsis git-mv commands in the synopsis section","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:16:03Z","receivedAt":"2025-03-30T17:16:11Z","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?= \n\nThis also entails changing the help output for the command to match the new\nsynopsis.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-mv.adoc | 6 ++----\n builtin/mv.c | 3 ++-\n 2 files changed, 4 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc\nindex dc1bf615341..08d660643fc 100644\n--- a/Documentation/git-mv.adoc\n+++ b/Documentation/git-mv.adoc\n@@ -9,15 +9,13 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [] ... \n+'git mv' [-v] [-f] [-n] [-k] \n+'git mv' [-v] [-f] [-n] [-k] ... \n \n DESCRIPTION\n -----------\n Move or rename a file, directory, or symlink.\n \n- git mv [-v] [-f] [-n] [-k] \n- git mv [-v] [-f] [-n] [-k] ... \n-\n In the first form, it renames , which must exist and be either\n a file, symlink or directory, to .\n In the second form, the last argument has to be an existing\ndiff --git a/builtin/mv.c b/builtin/mv.c\nindex 55a7d471dca..9e36b616ab6 100644\n--- a/builtin/mv.c\n+++ b/builtin/mv.c\n@@ -28,7 +28,8 @@\n #include \"entry.h\"\n \n static const char * const builtin_mv_usage[] = {\n-\tN_(\"git mv [] ... \"),\n+\tN_(\"git mv [-v] [-f] [-n] [-k] \"),\n+\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n \tNULL\n };\n \n-- \ngitgitgadget\n\n"},{"id":"515307","messageId":"4887567c57cd54b8f5989d1d05a9a7a9663665b1.1743354964.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH 5/5] doc: convert git-mv to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-03-30T17:16:04Z","receivedAt":"2025-03-30T17:16:13Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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\nUnfortunately, there's an inconsistency in the synopsis style, where\nthe ellipsis is used to indicate that the option can be repeated, but\nit can also be used in Git's three-dot notation to indicate a range of\ncommits. The rendering engine will not be able to distinguish\nbetween these two cases.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-mv.adoc | 31 ++++++++++++++++---------------\n 1 file changed, 16 insertions(+), 15 deletions(-)\n\ndiff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc\nindex 08d660643fc..a0b8118cf4f 100644\n--- a/Documentation/git-mv.adoc\n+++ b/Documentation/git-mv.adoc\n@@ -8,17 +8,18 @@ git-mv - Move or rename a file, a directory, or a symlink\n \n SYNOPSIS\n --------\n-[verse]\n-'git mv' [-v] [-f] [-n] [-k] \n-'git mv' [-v] [-f] [-n] [-k] ... \n+\n+[synopsis]\n+git mv [-v] [-f] [-n] [-k] \n+git mv [-v] [-f] [-n] [-k] ... \n \n DESCRIPTION\n -----------\n Move or rename a file, directory, or symlink.\n \n-In the first form, it renames , which must exist and be either\n-a file, symlink or directory, to .\n-In the second form, the last argument has to be an existing\n+In the first form, it renames __, which must exist and be either\n+a file, symlink or directory, to __.\n+In the second form, __ has to be an existing\n directory; the given sources will be moved into this directory.\n \n The index is updated after successful completion, but the change must still be\n@@ -26,20 +27,20 @@ committed.\n \n OPTIONS\n -------\n--f::\n---force::\n+`-f`::\n+`--force`::\n \tForce renaming or moving of a file even if the exists.\n--k::\n+`-k`::\n \tSkip move or rename actions which would lead to an error\n \tcondition. An error happens when a source is neither existing nor\n \tcontrolled by Git, or when it would overwrite an existing\n \tfile unless `-f` is given.\n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDo nothing; only show what would happen\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tReport the names of files as they are moved.\n \n SUBMODULES\n@@ -47,8 +48,8 @@ SUBMODULES\n Moving a submodule using a gitfile (which means they were cloned\n with a Git version 1.7.8 or newer) will update the gitfile and\n core.worktree setting to make the submodule work in the new location.\n-It also will attempt to update the submodule..path setting in\n-the linkgit:gitmodules[5] file and stage that file (unless -n is used).\n+It also will attempt to update the `submodule..path` setting in\n+the linkgit:gitmodules[5] file and stage that file (unless `-n` is used).\n \n BUGS\n ----\n-- \ngitgitgadget\n"},{"id":"515681","messageId":"CAN0heSpQVWEko_=Ld1yQvduH4amB+Ei8Gf2pOjWA1Y4Pq7GSKA@mail.gmail.com","threadId":"63218","inReplyTo":"1676b5ac628fd2898c3dab1b25d6a852cedfa6ae.1743354964.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 1/5] doc: convert git-reset to new documentation format","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-04-04T16:39:42Z","receivedAt":"2025-04-04T16:39:57Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Hi Jean-Noël,\n\nOn Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget\n wrote:\n\n> - Switch the synopsis to a synopsis block which will automatically\n> format placeholders in italics and keywords in monospace\n> - Use __ instead of 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> ---soft::\n> +`--soft`::\n> Does not touch the index file or the working tree at all (but\n> - resets the head to ``, just like all modes do). This leaves\n> - all your changed files \"Changes to be committed\", as `git status`\n> + resets the head to __, just like all modes do). This leaves\n> + all your changed files \"Changes to be committed\", as `git status\n> would put it.\n\nThis loses the closing backtick after \"git status\".\n\n> ---pathspec-from-file=::\n> - Pathspec is passed in `` instead of commandline args. If\n> - `` is exactly `-` then standard input is used. Pathspec\n> - elements are separated by LF or CR/LF. Pathspec elements can be\n> +`--pathspec-from-file=`::\n> + Pathspec is passed in __ instead of commandline args. If\n> + __ is exactly `-` then standard input is used. Pathspec\n> + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n> quoted as explained for the configuration variable `core.quotePath`\n> (see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n> global `--literal-pathspecs`.\n>\n> ---pathspec-file-nul::\n> +`--pathspec-file-nul`::\n> Only meaningful with `--pathspec-from-file`. Pathspec elements are\n> - separated with NUL character and all other characters are taken\n> + separated with _NUL_ character and all other characters are taken\n> literally (including newlines and quotes).\n\nI was surprised that you wrapped CR, LF, and NUL in underscores. The\ncommit message only talks about , similar to\nCodingGuidelines. That said, these _CR_ and friends seem to be\nconsistent with similar conversions you've done before.\n\n\nMartin\n"},{"id":"515682","messageId":"CAN0heSrfQMZ8=pFNuaqn_0bpLxhMtGiO8Vg2hXTo6aqq3rF4yQ@mail.gmail.com","threadId":"63218","inReplyTo":"6206e65ac4d50e174ad7e3dbafaa590b632f214b.1743354964.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 2/5] doc: fix synopsis analysis logic","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-04-04T16:39:56Z","receivedAt":"2025-04-04T16:40:11Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget\n wrote:\n>\n> The synopsis analysis logic was not able to handle backslashes and stars\n> which are used in the synopsis of the git-rm command. This patch fixes the\n> issue by updating the regular expression used to match the keywords.\n\n> --- a/Documentation/asciidoctor-extensions.rb.in\n> +++ b/Documentation/asciidoctor-extensions.rb.in\n> @@ -50,7 +50,7 @@ module Git\n> def process parent, reader, attrs\n> outlines = reader.lines.map do |l|\n> l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n> - .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n> + .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+)}, '\\1{empty}`\\2`{empty}')\n> .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n> .gsub(']', ']{empty}')\n> end\n> @@ -72,7 +72,7 @@ module Git\n> %()\n> elsif type == :monospaced\n> node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n> - .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n> + .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n> .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n> else\n> open, close, supports_phrase = QUOTE_TAGS[type]\n> @@ -100,7 +100,7 @@ module Git\n> def convert_inline_quoted node\n> if node.type == :monospaced\n> node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n> - .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n> + .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n> .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n\nThis seems to introduce some extra spacing in the rendered man pages, e.g.,\n\"The bundle.* keys\" or \"Fileglobs (e.g. *.c)\". (Asciidoctor 2.0.18.) I\nhaven't dug into the regexes so see what might be the cause.\n\n(I only had time to have a look at the first patch, then briefly trying out\nthis one.)\n\n\nMartin\n"},{"id":"515695","messageId":"CAN0heSodC8_Uwg_Lw31rtkdLfOEDyGg=iE0gb1TRrUWQEynT+w@mail.gmail.com","threadId":"63218","inReplyTo":"9f7cd02cc1ef76bfe92cbb8152f34460c67b2eda.1743354964.git.gitgitgadget@gmail.com","subject":"Re: [PATCH 4/5] doc: move synopsis git-mv commands in the synopsis section","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-04-05T10:57:54Z","receivedAt":"2025-04-05T10:58:08Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget\n wrote:\n\n> [verse]\n> -'git mv' [] ... \n> +'git mv' [-v] [-f] [-n] [-k] \n> +'git mv' [-v] [-f] [-n] [-k] ... \n\nShouldn't \"...\" be tucked with the preceding \"\", i.e.,\n\"...\" as it was in the original?\n\n> DESCRIPTION\n> -----------\n> Move or rename a file, directory, or symlink.\n>\n> - git mv [-v] [-f] [-n] [-k] \n> - git mv [-v] [-f] [-n] [-k] ... \n> -\n\nThis is where \" ...\" comes from. You moved these lines up. Good.\nBut I do think we want \"...\"?\n\nMartin\n"},{"id":"516031","messageId":"0846bdd8-f2a6-43d9-83d1-73d9a5b04005@free.fr","threadId":"63218","inReplyTo":"CAN0heSrfQMZ8=pFNuaqn_0bpLxhMtGiO8Vg2hXTo6aqq3rF4yQ@mail.gmail.com","subject":"Re: [PATCH 2/5] doc: fix synopsis analysis logic","fromName":"Jean-Noël Avila","fromEmail":"jn.avila@free.fr","sentAt":"2025-04-12T08:58:37Z","receivedAt":"2025-04-12T09:05:49Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"Le 05/04/2025 à 00:39, Martin Ågren a écrit :\n> On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget\n> wrote:\n>>\n>> The synopsis analysis logic was not able to handle backslashes and stars\n>> which are used in the synopsis of the git-rm command. This patch fixes the\n>> issue by updating the regular expression used to match the keywords.\n> \n>> --- a/Documentation/asciidoctor-extensions.rb.in\n>> +++ b/Documentation/asciidoctor-extensions.rb.in\n>> @@ -50,7 +50,7 @@ module Git\n>> def process parent, reader, attrs\n>> outlines = reader.lines.map do |l|\n>> l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n>> - .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n>> + .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+)}, '\\1{empty}`\\2`{empty}')\n>> .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n>> .gsub(']', ']{empty}')\n>> end\n>> @@ -72,7 +72,7 @@ module Git\n>> %()\n>> elsif type == :monospaced\n>> node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n>> - .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n>> + .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n>> .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n>> else\n>> open, close, supports_phrase = QUOTE_TAGS[type]\n>> @@ -100,7 +100,7 @@ module Git\n>> def convert_inline_quoted node\n>> if node.type == :monospaced\n>> node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n>> - .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n>> + .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n>> .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n> \n> This seems to introduce some extra spacing in the rendered man pages, e.g.,\n> \"The bundle.* keys\" or \"Fileglobs (e.g. *.c)\". (Asciidoctor 2.0.18.) I\n> haven't dug into the regexes so see what might be the cause.\n> \n\nThe xml regex seems ok for this. The docbook output is as follows:\n\n(...)\npairs in this list are in the bundle.* namespace (see\n(...)\n\nThe manpage output seems also correct:\n\n(...)\nwould accept (with the\n\\fB\\-\\-file\\fR\noption)\\&. The key\\-value pairs in this list are in the\n\\fBbundle\\&.*\\fR\nnamespace (see\n(...)\n\nStrangely, the --file above is rendered correctly, but the bundle.*\nbelow not. I do not know TROFF to assess what is going on. Has '*' a\nspecial behavior in a bold span?\n\nJN\n\n"},{"id":"516035","messageId":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.git.1743354964.gitgitgadget@gmail.com","subject":"[PATCH v2 0/7] doc: convert git-reset, git-rm and git-mv to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:43Z","receivedAt":"2025-04-12T12:20:54Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"doc: convert git-reset, git-rm and git-mv to new documentation format\n\nchange since V1:\n\n * fix remarks from reviewers\n * stack the commit fixing the handling of three-dot notation\n\nJean-Noël Avila (7):\n doc: convert git-reset to new documentation format\n doc: fix synopsis analysis logic\n doc: convert git-rm to new documentation format\n doc: move synopsis git-mv commands in the synopsis section\n doc: convert git-mv to new documentation format\n doc: fix asciidoctor synopsis processing of triple-dots\n doc: add markup for characters in Guidelines\n\n Documentation/CodingGuidelines | 3 +\n Documentation/asciidoc.conf.in | 8 +-\n Documentation/asciidoctor-extensions.rb.in | 12 +--\n Documentation/git-mv.adoc | 33 ++++----\n Documentation/git-reset.adoc | 98 +++++++++++-----------\n Documentation/git-rm.adoc | 56 ++++++-------\n builtin/mv.c | 3 +-\n 7 files changed, 109 insertions(+), 104 deletions(-)\n\n\nbase-commit: 485f5f863615e670fd97ae40af744e14072cfe18\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1896%2Fjnavila%2Fdoc_git_reset-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1896/jnavila/doc_git_reset-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1896\n\nRange-diff vs v1:\n\n 1: 1676b5ac628 ! 1: 5a6c7def260 doc: convert git-reset to new documentation format\n @@ Documentation/git-reset.adoc: and specifying a commit with `--source`, you\n +`--soft`::\n \tDoes not touch the index file or the working tree at all (but\n -\tresets the head to ``, just like all modes do). This leaves\n --\tall your changed files \"Changes to be committed\", as `git status`\n +\tresets the head to __, just like all modes do). This leaves\n -+\tall your changed files \"Changes to be committed\", as `git status\n + \tall your changed files \"Changes to be committed\", as `git status`\n \twould put it.\n \n ---mixed::\n 2: 6206e65ac4d = 2: 440eac1f974 doc: fix synopsis analysis logic\n 3: 41a01969d93 = 3: 6814e98f71d doc: convert git-rm to new documentation format\n 4: 9f7cd02cc1e = 4: 2a129734e3d doc: move synopsis git-mv commands in the synopsis section\n 5: 4887567c57c ! 5: 1868dfc3282 doc: convert git-mv to new documentation format\n @@ Documentation/git-mv.adoc: git-mv - Move or rename a file, a directory, or a sym\n +\n +[synopsis]\n +git mv [-v] [-f] [-n] [-k] \n -+git mv [-v] [-f] [-n] [-k] ... \n ++git mv [-v] [-f] [-n] [-k] ... \n \n DESCRIPTION\n -----------\n @@ Documentation/git-mv.adoc: SUBMODULES\n \n BUGS\n ----\n +\n + ## builtin/mv.c ##\n +@@\n + \n + static const char * const builtin_mv_usage[] = {\n + \tN_(\"git mv [-v] [-f] [-n] [-k] \"),\n +-\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n ++\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n + \tNULL\n + };\n + \n -: ----------- > 6: 2ddce76f14d doc: fix asciidoctor synopsis processing of triple-dots\n -: ----------- > 7: 2690f84602b doc: add markup for characters in Guidelines\n\n-- \ngitgitgadget\n"},{"id":"516036","messageId":"5a6c7def2608219ac4069a6da3afe96242695ef1.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 1/7] doc: convert git-reset to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:44Z","receivedAt":"2025-04-12T12:20:55Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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 \n---\n Documentation/git-reset.adoc | 98 ++++++++++++++++++------------------\n 1 file changed, 49 insertions(+), 49 deletions(-)\n\ndiff --git a/Documentation/git-reset.adoc b/Documentation/git-reset.adoc\nindex 79ad5643eed..53ab88c5451 100644\n--- a/Documentation/git-reset.adoc\n+++ b/Documentation/git-reset.adoc\n@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state\n \n SYNOPSIS\n --------\n-[verse]\n-'git reset' [-q] [] [--] ...\n-'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n-'git reset' (--patch | -p) [] [--] [...]\n-'git reset' [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n+[synopsis]\n+git reset [-q] [] [--] ...\n+git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []\n+git reset (--patch | -p) [] [--] [...]\n+git reset [--soft | --mixed [-N] | --hard | --merge | --keep] [-q] []\n \n DESCRIPTION\n -----------\n-In the first three forms, copy entries from `` to the index.\n-In the last form, set the current branch head (`HEAD`) to ``,\n+In the first three forms, copy entries from __ to the index.\n+In the last form, set the current branch head (`HEAD`) to __,\n optionally modifying index and working tree to match.\n-The ``/`` defaults to `HEAD` in all forms.\n+The __/__ defaults to `HEAD` in all forms.\n \n-'git reset' [-q] [] [--] ...::\n-'git reset' [-q] [--pathspec-from-file= [--pathspec-file-nul]] []::\n+`git reset [-q] [] [--] ...`::\n+`git reset [-q] [--pathspec-from-file= [--pathspec-file-nul]] []`::\n \tThese forms reset the index entries for all paths that match the\n-\t`` to their state at ``. (It does not affect\n+\t__ to their state at __. (It does not affect\n \tthe working tree or the current branch.)\n +\n This means that `git reset ` is the opposite of `git add\n@@ -37,30 +37,30 @@ and specifying a commit with `--source`, you\n can copy the contents of a path out of a commit to the index and to the\n working tree in one go.\n \n-'git reset' (--patch | -p) [] [--] [...]::\n+`git reset (--patch | -p) [] [--] [...]`::\n \tInteractively select hunks in the difference between the index\n-\tand `` (defaults to `HEAD`). The chosen hunks are applied\n+\tand __ (defaults to `HEAD`). The chosen hunks are applied\n \tin reverse to the index.\n +\n This means that `git reset -p` is the opposite of `git add -p`, i.e.\n-you can use it to selectively reset hunks. See the ``Interactive Mode''\n+you can use it to selectively reset hunks. See the \"Interactive Mode\"\n section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n \n-'git reset' [] []::\n-\tThis form resets the current branch head to `` and\n-\tpossibly updates the index (resetting it to the tree of ``) and\n-\tthe working tree depending on ``. Before the operation, `ORIG_HEAD`\n-\tis set to the tip of the current branch. If `` is omitted,\n-\tdefaults to `--mixed`. The `` must be one of the following:\n+`git reset [] []`::\n+\tThis form resets the current branch head to __ and\n+\tpossibly updates the index (resetting it to the tree of __) and\n+\tthe working tree depending on __. Before the operation, `ORIG_HEAD`\n+\tis set to the tip of the current branch. If __ is omitted,\n+\tdefaults to `--mixed`. The __ must be one of the following:\n +\n --\n---soft::\n+`--soft`::\n \tDoes not touch the index file or the working tree at all (but\n-\tresets the head to ``, just like all modes do). This leaves\n+\tresets the head to __, just like all modes do). This leaves\n \tall your changed files \"Changes to be committed\", as `git status`\n \twould put it.\n \n---mixed::\n+`--mixed`::\n \tResets the index but not the working tree (i.e., the changed files\n \tare preserved but not marked for commit) and reports what has not\n \tbeen updated. This is the default action.\n@@ -68,33 +68,33 @@ section of linkgit:git-add[1] to learn how to operate the `--patch` mode.\n If `-N` is specified, removed paths are marked as intent-to-add (see\n linkgit:git-add[1]).\n \n---hard::\n+`--hard`::\n \tResets the index and working tree. Any changes to tracked files in the\n-\tworking tree since `` are discarded. Any untracked files or\n+\tworking tree since __ are discarded. Any untracked files or\n \tdirectories in the way of writing any tracked files are simply deleted.\n \n---merge::\n+`--merge`::\n \tResets the index and updates the files in the working tree that are\n-\tdifferent between `` and `HEAD`, but keeps those which are\n+\tdifferent between __ and `HEAD`, but keeps those which are\n \tdifferent between the index and working tree (i.e. which have changes\n \twhich have not been added).\n-\tIf a file that is different between `` and the index has\n+\tIf a file that is different between __ and the index has\n \tunstaged changes, reset is aborted.\n +\n In other words, `--merge` does something like a `git read-tree -u -m `,\n but carries forward unmerged index entries.\n \n---keep::\n+`--keep`::\n \tResets index entries and updates files in the working tree that are\n-\tdifferent between `` and `HEAD`.\n-\tIf a file that is different between `` and `HEAD` has local\n+\tdifferent between __ and `HEAD`.\n+\tIf a file that is different between __ and `HEAD` has local\n \tchanges, reset is aborted.\n \n---[no-]recurse-submodules::\n-\tWhen the working tree is updated, using --recurse-submodules will\n+`--[no-]recurse-submodules`::\n+\tWhen the working tree is updated, using `--recurse-submodules` will\n \talso recursively reset the working tree of all active submodules\n \taccording to the commit recorded in the superproject, also setting\n-\tthe submodules' HEAD to be detached at that commit.\n+\tthe submodules' `HEAD` to be detached at that commit.\n --\n \n See \"Reset, restore and revert\" in linkgit:git[1] for the differences\n@@ -104,31 +104,31 @@ between the three commands.\n OPTIONS\n -------\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \tBe quiet, only report errors.\n \n---refresh::\n---no-refresh::\n+`--refresh`::\n+`--no-refresh`::\n \tRefresh the index after a mixed reset. Enabled by default.\n \n---pathspec-from-file=::\n-\tPathspec is passed in `` instead of commandline args. If\n-\t`` is exactly `-` then standard input is used. Pathspec\n-\telements are separated by LF or CR/LF. Pathspec elements can be\n+`--pathspec-from-file=`::\n+\tPathspec is passed in __ instead of commandline args. If\n+\t__ is exactly `-` then standard input is used. Pathspec\n+\telements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n \tglobal `--literal-pathspecs`.\n \n---pathspec-file-nul::\n+`--pathspec-file-nul`::\n \tOnly meaningful with `--pathspec-from-file`. Pathspec elements are\n-\tseparated with NUL character and all other characters are taken\n+\tseparated with _NUL_ character and all other characters are taken\n \tliterally (including newlines and quotes).\n \n-\\--::\n+`--`::\n \tDo not interpret any more arguments as options.\n \n-...::\n+`...`::\n \tLimits the paths affected by the operation.\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n@@ -348,7 +348,7 @@ $ git commit ... <8>\n ------------\n +\n <1> First, reset the history back one commit so that we remove the original\n- commit, but leave the working tree with all the changes. The -N ensures\n+ commit, but leave the working tree with all the changes. The `-N` ensures\n that any new files added with `HEAD` are still marked so that `git add -p`\n will find them.\n <2> Next, we interactively select diff hunks to add using the `git add -p`\n@@ -458,7 +458,7 @@ working index HEAD target working index HEAD\n \t\t\t --keep B C C\n ....\n \n-`reset --merge` is meant to be used when resetting out of a conflicted\n+`git reset --merge` is meant to be used when resetting out of a conflicted\n merge. Any mergy operation guarantees that the working tree file that is\n involved in the merge does not have a local change with respect to the index\n before it starts, and that it writes the result out to the working tree. So if\n@@ -467,7 +467,7 @@ between the index and the working tree, then it means that we are not\n resetting out from a state that a mergy operation left after failing\n with a conflict. That is why we disallow `--merge` option in this case.\n \n-`reset --keep` is meant to be used when removing some of the last\n+`git reset --keep` is meant to be used when removing some of the last\n commits in the current branch while keeping changes in the working\n tree. If there could be conflicts between the changes in the commit we\n want to remove and the changes in the working tree we want to keep,\n-- \ngitgitgadget\n\n"},{"id":"516037","messageId":"440eac1f974880b004992972385e4af030a6691e.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 2/7] doc: fix synopsis analysis logic","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:45Z","receivedAt":"2025-04-12T12:20:57Z","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?= \n\nThe synopsis analysis logic was not able to handle backslashes and stars\nwhich are used in the synopsis of the git-rm command. This patch fixes the\nissue by updating the regular expression used to match the keywords.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/asciidoc.conf.in | 8 ++++----\n Documentation/asciidoctor-extensions.rb.in | 6 +++---\n 2 files changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex f2aef6cb79f..50f0e81a831 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -43,7 +43,7 @@ ifdef::doctype-book[]\n endif::doctype-book[]\n \n [literal-inlinemacro]\n-{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\\\\\*\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n \n endif::backend-docbook[]\n \n@@ -75,18 +75,18 @@ git-relative-html-prefix=\n {target}{0?({0})}\n \n [literal-inlinemacro]\n-{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\\\\\*\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n \n endif::backend-xhtml11[]\n \n ifdef::backend-docbook[]\n ifdef::doctype-manpage[]\n [paradef-default]\n-synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::doctype-manpage[]\n endif::backend-docbook[]\n \n ifdef::backend-xhtml11[]\n [paradef-default]\n-synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n+synopsis-style=template=\"verseparagraph\",filter=\"sed 's!…\\\\(\\\\]\\\\|$\\\\)!\\\\0!g;s!\\\\([\\\\[ |()]\\\\|^\\\\|\\\\]\\\\|>\\\\)\\\\([-=a-zA-Z0-9:+@,\\\\/_^\\\\$.\\\\\\\\\\\\*]\\\\+\\\\|…\\\\)!\\\\1\\\\2!g;s!<[-a-zA-Z0-9.]\\\\+>!\\\\0!g'\"\n endif::backend-xhtml11[]\ndiff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\nindex 2494f17a514..09156b71a4f 100644\n--- a/Documentation/asciidoctor-extensions.rb.in\n+++ b/Documentation/asciidoctor-extensions.rb.in\n@@ -50,7 +50,7 @@ module Git\n def process parent, reader, attrs\n outlines = reader.lines.map do |l|\n l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n- .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$]+)}, '\\1{empty}`\\2`{empty}')\n+ .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+)}, '\\1{empty}`\\2`{empty}')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n .gsub(']', ']{empty}')\n end\n@@ -72,7 +72,7 @@ module Git\n %()\n elsif type == :monospaced\n node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n- .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n+ .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n else\n open, close, supports_phrase = QUOTE_TAGS[type]\n@@ -100,7 +100,7 @@ module Git\n def convert_inline_quoted node\n if node.type == :monospaced\n node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n- .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$]+\\.{0,2})+)}, '\\1\\2')\n+ .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n \n else\n-- \ngitgitgadget\n\n"},{"id":"516038","messageId":"6814e98f71d60d72664e7419ba79b7b3b5bb39bd.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 3/7] doc: convert git-rm to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:46Z","receivedAt":"2025-04-12T12:20:57Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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 \n---\n Documentation/git-rm.adoc | 56 +++++++++++++++++++--------------------\n 1 file changed, 28 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/git-rm.adoc b/Documentation/git-rm.adoc\nindex 363a26934f5..b5ead867963 100644\n--- a/Documentation/git-rm.adoc\n+++ b/Documentation/git-rm.adoc\n@@ -7,10 +7,10 @@ git-rm - Remove files from the working tree and from the index\n \n SYNOPSIS\n --------\n-[verse]\n-'git rm' [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n-\t [--quiet] [--pathspec-from-file= [--pathspec-file-nul]]\n-\t [--] [...]\n+[synopsis]\n+git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch]\n+ [--quiet] [--pathspec-from-file= [--pathspec-file-nul]]\n+ [--] [...]\n \n DESCRIPTION\n -----------\n@@ -30,7 +30,7 @@ sparse-checkouts are in use (see linkgit:git-sparse-checkout[1]),\n \n OPTIONS\n -------\n-...::\n+`...`::\n \tFiles to remove. A leading directory name (e.g. `dir` to remove\n \t`dir/file1` and `dir/file2`) can be given to remove all files in\n \tthe directory, and recursively all sub-directories, but this\n@@ -43,57 +43,57 @@ directories `d` and `d2`, there is a difference between using\n `git rm 'd*'` and `git rm 'd/*'`, as the former will also remove all\n of directory `d2`.\n +\n-For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n+For more details, see the __ entry in linkgit:gitglossary[7].\n \n--f::\n---force::\n+`-f`::\n+`--force`::\n \tOverride the up-to-date check.\n \n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDon't actually remove any file(s). Instead, just show\n \tif they exist in the index and would otherwise be removed\n \tby the command.\n \n--r::\n+`-r`::\n Allow recursive removal when a leading directory name is\n given.\n \n-\\--::\n+`--`::\n \tThis option can be used to separate command-line options from\n \tthe list of files, (useful when filenames might be mistaken\n \tfor command-line options).\n \n---cached::\n+`--cached`::\n \tUse this option to unstage and remove paths only from the index.\n \tWorking tree files, whether modified or not, will be\n \tleft alone.\n \n---ignore-unmatch::\n+`--ignore-unmatch`::\n \tExit with a zero status even if no files matched.\n \n---sparse::\n+`--sparse`::\n \tAllow updating index entries outside of the sparse-checkout cone.\n \tNormally, `git rm` refuses to update index entries whose paths do\n \tnot fit within the sparse-checkout cone. See\n \tlinkgit:git-sparse-checkout[1] for more.\n \n--q::\n---quiet::\n+`-q`::\n+`--quiet`::\n \t`git rm` normally outputs one line (in the form of an `rm` command)\n \tfor each file removed. This option suppresses that output.\n \n---pathspec-from-file=::\n-\tPathspec is passed in `` instead of commandline args. If\n-\t`` is exactly `-` then standard input is used. Pathspec\n-\telements are separated by LF or CR/LF. Pathspec elements can be\n+`--pathspec-from-file=`::\n+\tPathspec is passed in __ instead of args. If\n+\t__ is exactly `-` then standard input is used. Pathspec\n+\telements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be\n \tquoted as explained for the configuration variable `core.quotePath`\n \t(see linkgit:git-config[1]). See also `--pathspec-file-nul` and\n \tglobal `--literal-pathspecs`.\n \n---pathspec-file-nul::\n+`--pathspec-file-nul`::\n \tOnly meaningful with `--pathspec-from-file`. Pathspec elements are\n-\tseparated with NUL character and all other characters are taken\n+\tseparated with _NUL_ character and all other characters are taken\n \tliterally (including newlines and quotes).\n \n \n@@ -153,15 +153,15 @@ SUBMODULES\n ----------\n Only submodules using a gitfile (which means they were cloned\n with a Git version 1.7.8 or newer) will be removed from the work\n-tree, as their repository lives inside the .git directory of the\n+tree, as their repository lives inside the `.git` directory of the\n superproject. If a submodule (or one of those nested inside it)\n-still uses a .git directory, `git rm` will move the submodules\n+still uses a `.git` directory, `git rm` moves the submodules\n git directory into the superprojects git directory to protect\n-the submodule's history. If it exists the submodule. section\n+the submodule's history. If it exists the `submodule.` section\n in the linkgit:gitmodules[5] file will also be removed and that file\n-will be staged (unless --cached or -n are used).\n+will be staged (unless `--cached` or `-n` are used).\n \n-A submodule is considered up to date when the HEAD is the same as\n+A submodule is considered up to date when the `HEAD` is the same as\n recorded in the index, no tracked files are modified and no untracked\n files that aren't ignored are present in the submodule's work tree.\n Ignored files are deemed expendable and won't stop a submodule's work\n-- \ngitgitgadget\n\n"},{"id":"516039","messageId":"2a129734e3d6c7714186f48f916a48dc7535f91b.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 4/7] doc: move synopsis git-mv commands in the synopsis section","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:47Z","receivedAt":"2025-04-12T12:20:58Z","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?= \n\nThis also entails changing the help output for the command to match the new\nsynopsis.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-mv.adoc | 6 ++----\n builtin/mv.c | 3 ++-\n 2 files changed, 4 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc\nindex dc1bf615341..08d660643fc 100644\n--- a/Documentation/git-mv.adoc\n+++ b/Documentation/git-mv.adoc\n@@ -9,15 +9,13 @@ git-mv - Move or rename a file, a directory, or a symlink\n SYNOPSIS\n --------\n [verse]\n-'git mv' [] ... \n+'git mv' [-v] [-f] [-n] [-k] \n+'git mv' [-v] [-f] [-n] [-k] ... \n \n DESCRIPTION\n -----------\n Move or rename a file, directory, or symlink.\n \n- git mv [-v] [-f] [-n] [-k] \n- git mv [-v] [-f] [-n] [-k] ... \n-\n In the first form, it renames , which must exist and be either\n a file, symlink or directory, to .\n In the second form, the last argument has to be an existing\ndiff --git a/builtin/mv.c b/builtin/mv.c\nindex 55a7d471dca..9e36b616ab6 100644\n--- a/builtin/mv.c\n+++ b/builtin/mv.c\n@@ -28,7 +28,8 @@\n #include \"entry.h\"\n \n static const char * const builtin_mv_usage[] = {\n-\tN_(\"git mv [] ... \"),\n+\tN_(\"git mv [-v] [-f] [-n] [-k] \"),\n+\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n \tNULL\n };\n \n-- \ngitgitgadget\n\n"},{"id":"516040","messageId":"1868dfc3282636ba20feacd5ebfc5107869b26e2.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 5/7] doc: convert git-mv to new documentation format","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:48Z","receivedAt":"2025-04-12T12:21:00Z","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?= \n\n- Switch the synopsis to a synopsis block which will automatically\n format placeholders in italics and keywords in monospace\n- Use __ instead of 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\nUnfortunately, there's an inconsistency in the synopsis style, where\nthe ellipsis is used to indicate that the option can be repeated, but\nit can also be used in Git's three-dot notation to indicate a range of\ncommits. The rendering engine will not be able to distinguish\nbetween these two cases.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/git-mv.adoc | 31 ++++++++++++++++---------------\n builtin/mv.c | 2 +-\n 2 files changed, 17 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-mv.adoc b/Documentation/git-mv.adoc\nindex 08d660643fc..f707e998f77 100644\n--- a/Documentation/git-mv.adoc\n+++ b/Documentation/git-mv.adoc\n@@ -8,17 +8,18 @@ git-mv - Move or rename a file, a directory, or a symlink\n \n SYNOPSIS\n --------\n-[verse]\n-'git mv' [-v] [-f] [-n] [-k] \n-'git mv' [-v] [-f] [-n] [-k] ... \n+\n+[synopsis]\n+git mv [-v] [-f] [-n] [-k] \n+git mv [-v] [-f] [-n] [-k] ... \n \n DESCRIPTION\n -----------\n Move or rename a file, directory, or symlink.\n \n-In the first form, it renames , which must exist and be either\n-a file, symlink or directory, to .\n-In the second form, the last argument has to be an existing\n+In the first form, it renames __, which must exist and be either\n+a file, symlink or directory, to __.\n+In the second form, __ has to be an existing\n directory; the given sources will be moved into this directory.\n \n The index is updated after successful completion, but the change must still be\n@@ -26,20 +27,20 @@ committed.\n \n OPTIONS\n -------\n--f::\n---force::\n+`-f`::\n+`--force`::\n \tForce renaming or moving of a file even if the exists.\n--k::\n+`-k`::\n \tSkip move or rename actions which would lead to an error\n \tcondition. An error happens when a source is neither existing nor\n \tcontrolled by Git, or when it would overwrite an existing\n \tfile unless `-f` is given.\n--n::\n---dry-run::\n+`-n`::\n+`--dry-run`::\n \tDo nothing; only show what would happen\n \n--v::\n---verbose::\n+`-v`::\n+`--verbose`::\n \tReport the names of files as they are moved.\n \n SUBMODULES\n@@ -47,8 +48,8 @@ SUBMODULES\n Moving a submodule using a gitfile (which means they were cloned\n with a Git version 1.7.8 or newer) will update the gitfile and\n core.worktree setting to make the submodule work in the new location.\n-It also will attempt to update the submodule..path setting in\n-the linkgit:gitmodules[5] file and stage that file (unless -n is used).\n+It also will attempt to update the `submodule..path` setting in\n+the linkgit:gitmodules[5] file and stage that file (unless `-n` is used).\n \n BUGS\n ----\ndiff --git a/builtin/mv.c b/builtin/mv.c\nindex 9e36b616ab6..d673a6c83ef 100644\n--- a/builtin/mv.c\n+++ b/builtin/mv.c\n@@ -29,7 +29,7 @@\n \n static const char * const builtin_mv_usage[] = {\n \tN_(\"git mv [-v] [-f] [-n] [-k] \"),\n-\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n+\tN_(\"git mv [-v] [-f] [-n] [-k] ... \"),\n \tNULL\n };\n \n-- \ngitgitgadget\n\n"},{"id":"516041","messageId":"2ddce76f14d226d9f1b7b3efe5a27a4e812be60b.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 6/7] doc: fix asciidoctor synopsis processing of triple-dots","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:49Z","receivedAt":"2025-04-12T12:21:01Z","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?= \n\nThe processing of triple dot notation is tricky because it can be\nmis-interpreted as an ellipsis. The special processing of the ellipsis\nis now complete and takes into account the case of\n`git-mv ... `\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/asciidoc.conf.in | 2 +-\n Documentation/asciidoctor-extensions.rb.in | 8 +++++---\n 2 files changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/asciidoc.conf.in b/Documentation/asciidoc.conf.in\nindex 50f0e81a831..9d9139306e6 100644\n--- a/Documentation/asciidoc.conf.in\n+++ b/Documentation/asciidoc.conf.in\n@@ -43,7 +43,7 @@ ifdef::doctype-book[]\n endif::doctype-book[]\n \n [literal-inlinemacro]\n-{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,\\\\\\*\\/_^\\$]+\\.?)+)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n+{eval:re.sub(r'(<[-a-zA-Z0-9.]+>)', r'\\1', re.sub(r'([\\[\\s|()>]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@\\\\\\*\\/_^\\$]+\\.?)+|,)',r'\\1\\2', re.sub(r'(\\.\\.\\.?)([^\\]$.])', r'\\1\\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}\n \n endif::backend-docbook[]\n \ndiff --git a/Documentation/asciidoctor-extensions.rb.in b/Documentation/asciidoctor-extensions.rb.in\nindex 09156b71a4f..8b7b1613496 100644\n--- a/Documentation/asciidoctor-extensions.rb.in\n+++ b/Documentation/asciidoctor-extensions.rb.in\n@@ -49,7 +49,7 @@ module Git\n \n def process parent, reader, attrs\n outlines = reader.lines.map do |l|\n- l.gsub(/(\\.\\.\\.?)([^\\]$.])/, '`\\1`\\2')\n+ l.gsub(/(\\.\\.\\.?)([^\\]$\\. ])/, '{empty}`\\1`{empty}\\2')\n .gsub(%r{([\\[\\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+)}, '\\1{empty}`\\2`{empty}')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\\\1__')\n .gsub(']', ']{empty}')\n@@ -71,8 +71,9 @@ module Git\n # unhandled math; pass source to alt and required mathphrase element; dblatex will process alt as LaTeX math\n %()\n elsif type == :monospaced\n- node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n- .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n+ node.text.gsub(/(\\.\\.\\.?)([^\\]$\\.])/, '\\1\\2')\n+ .gsub(/^\\.\\.\\.?$/, '\\0')\n+ .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@/_^\\$\\\\\\*]+\\.{0,2})+|,)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n else\n open, close, supports_phrase = QUOTE_TAGS[type]\n@@ -100,6 +101,7 @@ module Git\n def convert_inline_quoted node\n if node.type == :monospaced\n node.text.gsub(/(\\.\\.\\.?)([^\\]$.])/, '\\1\\2')\n+ .gsub(/^\\.\\.\\.?$/, '\\0')\n .gsub(%r{([\\[\\s|()>.]|^|\\]|>)(\\.?([-a-zA-Z0-9:+=~@,/_^\\$\\\\\\*]+\\.{0,2})+)}, '\\1\\2')\n .gsub(/(<[-a-zA-Z0-9.]+>)/, '\\1')\n \n-- \ngitgitgadget\n\n"},{"id":"516042","messageId":"2690f84602b89f1b10652a6381aa96b2e126d6eb.1744460450.git.gitgitgadget@gmail.com","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"[PATCH v2 7/7] doc: add markup for characters in Guidelines","fromName":"Jean-Noël Avila via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2025-04-12T12:20:50Z","receivedAt":"2025-04-12T12:21:02Z","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?= \n\nThis rule was already implicitely applied in the converted man pages,\nso let's state it loudly.\n\nSigned-off-by: Jean-Noël Avila \n---\n Documentation/CodingGuidelines | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex a0e7041c54b..c1046abfb7d 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -861,6 +861,9 @@ Markup:\n __\n __\n \n+Characters are also surrounded by underscores:\n+ _LF_, _CR_, _CR_/_LF_, _NUL_, _EOF_\n+\n Git's Asciidoc processor has been tailored to treat backticked text\n as complex synopsis. When literal and placeholders are mixed, you can\n use the backtick notation which will take care of correctly typesetting\n-- \ngitgitgadget\n"},{"id":"516149","messageId":"xmqqbjsypg97.fsf@gitster.g","threadId":"63218","inReplyTo":"pull.1896.v2.git.1744460450.gitgitgadget@gmail.com","subject":"Re: [PATCH v2 0/7] doc: convert git-reset, git-rm and git-mv to new documentation format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-14T21:47:32Z","receivedAt":"2025-04-14T21:47:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Jean-Noël Avila via GitGitGadget\" writes:\n\n> doc: convert git-reset, git-rm and git-mv to new documentation format\n>\n> change since V1:\n>\n> * fix remarks from reviewers\n> * stack the commit fixing the handling of three-dot notation\n>\n> Jean-Noël Avila (7):\n> doc: convert git-reset to new documentation format\n> doc: fix synopsis analysis logic\n> doc: convert git-rm to new documentation format\n> doc: move synopsis git-mv commands in the synopsis section\n> doc: convert git-mv to new documentation format\n\nIt was very obvious that the updates for the above relative to the\nprevious iteration are all good ones.\n\n> doc: fix asciidoctor synopsis processing of triple-dots\n\nI'll need to look at this a bit carefully, as regexp over\n tend to become pure gibberish ;-)\n\n> doc: add markup for characters in Guidelines\n\nLooking good.\n\nWill queue. Thanks.\n"}]}