doc: convert git-reset, git-rm and git-mv to new documentation format #1896

jnavila · 2025-03-28T13:48:58Z

doc: convert git-reset, git-rm and git-mv to new documentation format

change since V1:

fix remarks from reviewers
stack the commit fixing the handling of three-dot notation

cc: Martin Ågren [email protected]

jnavila · 2025-03-30T17:15:16Z

/submit

gitgitgadget · 2025-03-30T17:16:20Z

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1896/jnavila/doc_git_reset-v1

To fetch this version to local tag pr-1896/jnavila/doc_git_reset-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1896/jnavila/doc_git_reset-v1

gitgitgadget · 2025-04-01T14:10:38Z

This patch series was integrated into seen via git@521500a.

gitgitgadget · 2025-04-04T16:44:29Z

Documentation/git-reset.adoc

@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state



On the Git mailing list, Martin Ågren wrote (reply to this):

Hi Jean-Noël, On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget <[email protected]> wrote: > - Switch the synopsis to a synopsis block which will automatically > format placeholders in italics and keywords in monospace > - Use _<placeholder>_ instead of <placeholder> in the description > - Use `backticks` for keywords and more complex option > descriptions. The new rendering engine will apply synopsis rules to > these spans. > ---soft:: > +`--soft`:: > Does not touch the index file or the working tree at all (but > - resets the head to `<commit>`, just like all modes do). This leaves > - all your changed files "Changes to be committed", as `git status` > + resets the head to _<commit>_, just like all modes do). This leaves > + all your changed files "Changes to be committed", as `git status > would put it. This loses the closing backtick after "git status". > ---pathspec-from-file=<file>:: > - Pathspec is passed in `<file>` instead of commandline args. If > - `<file>` is exactly `-` then standard input is used. Pathspec > - elements are separated by LF or CR/LF. Pathspec elements can be > +`--pathspec-from-file=<file>`:: > + Pathspec is passed in _<file>_ instead of commandline args. If > + _<file>_ is exactly `-` then standard input is used. Pathspec > + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be > quoted as explained for the configuration variable `core.quotePath` > (see linkgit:git-config[1]). See also `--pathspec-file-nul` and > global `--literal-pathspecs`. > > ---pathspec-file-nul:: > +`--pathspec-file-nul`:: > Only meaningful with `--pathspec-from-file`. Pathspec elements are > - separated with NUL character and all other characters are taken > + separated with _NUL_ character and all other characters are taken > literally (including newlines and quotes). I was surprised that you wrapped CR, LF, and NUL in underscores. The commit message only talks about <placeholders>, similar to CodingGuidelines. That said, these _CR_ and friends seem to be consistent with similar conversions you've done before. Martin

gitgitgadget · 2025-04-04T16:44:31Z

User Martin Ågren <[email protected]> has been added to the cc: list.

gitgitgadget · 2025-04-04T16:44:32Z

Documentation/asciidoc.conf.in

@@ -43,7 +43,7 @@ ifdef::doctype-book[]
 endif::doctype-book[]


On the Git mailing list, Martin Ågren wrote (reply to this):

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget <[email protected]> wrote: > > The synopsis analysis logic was not able to handle backslashes and stars > which are used in the synopsis of the git-rm command. This patch fixes the > issue by updating the regular expression used to match the keywords. > --- a/Documentation/asciidoctor-extensions.rb.in > +++ b/Documentation/asciidoctor-extensions.rb.in > @@ -50,7 +50,7 @@ module Git > def process parent, reader, attrs > outlines = reader.lines.map do |l| > l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2') > - .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}') > + .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}') > .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') > .gsub(']', ']{empty}') > end > @@ -72,7 +72,7 @@ module Git > %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>) > elsif type == :monospaced > node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2') > - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>') > + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<literal>\2</literal>') > .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') > else > open, close, supports_phrase = QUOTE_TAGS[type] > @@ -100,7 +100,7 @@ module Git > def convert_inline_quoted node > if node.type == :monospaced > node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2') > - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>') > + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>') > .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') This seems to introduce some extra spacing in the rendered man pages, e.g., "The bundle.* keys" or "Fileglobs (e.g. *.c)". (Asciidoctor 2.0.18.) I haven't dug into the regexes so see what might be the cause. (I only had time to have a look at the first patch, then briefly trying out this one.) Martin

On the Git mailing list, Jean-Noël Avila wrote (reply to this):

Le 05/04/2025 à 00:39, Martin Ågren a écrit : > On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget > <[email protected]> wrote: >> >> The synopsis analysis logic was not able to handle backslashes and stars >> which are used in the synopsis of the git-rm command. This patch fixes the >> issue by updating the regular expression used to match the keywords. > >> --- a/Documentation/asciidoctor-extensions.rb.in >> +++ b/Documentation/asciidoctor-extensions.rb.in >> @@ -50,7 +50,7 @@ module Git >> def process parent, reader, attrs >> outlines = reader.lines.map do |l| >> l.gsub(/(\.\.\.?)([^\]$.])/, '`\1`\2') >> - .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$]+)}, '\1{empty}`\2`{empty}') >> + .gsub(%r{([\[\] |()>]|^)([-a-zA-Z0-9:+=~@,/_^\$\\\*]+)}, '\1{empty}`\2`{empty}') >> .gsub(/(<[-a-zA-Z0-9.]+>)/, '__\\1__') >> .gsub(']', ']{empty}') >> end >> @@ -72,7 +72,7 @@ module Git >> %(<inlineequation><alt><![CDATA[#{equation = node.text}]]></alt><mathphrase><![CDATA[#{equation}]]></mathphrase></inlineequation>) >> elsif type == :monospaced >> node.text.gsub(/(\.\.\.?)([^\]$.])/, '<literal>\1</literal>\2') >> - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<literal>\2</literal>') >> + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<literal>\2</literal>') >> .gsub(/(<[-a-zA-Z0-9.]+>)/, '<emphasis>\1</emphasis>') >> else >> open, close, supports_phrase = QUOTE_TAGS[type] >> @@ -100,7 +100,7 @@ module Git >> def convert_inline_quoted node >> if node.type == :monospaced >> node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2') >> - .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$]+\.{0,2})+)}, '\1<code>\2</code>') >> + .gsub(%r{([\[\s|()>.]|^|\]|>)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>') >> .gsub(/(<[-a-zA-Z0-9.]+>)/, '<em>\1</em>') > > This seems to introduce some extra spacing in the rendered man pages, e.g., > "The bundle.* keys" or "Fileglobs (e.g. *.c)". (Asciidoctor 2.0.18.) I > haven't dug into the regexes so see what might be the cause. > The xml regex seems ok for this. The docbook output is as follows: (...) pairs in this list are in the <literal>bundle.*</literal> namespace (see (...) The manpage output seems also correct: (...) would accept (with the \fB\-\-file\fR option)\&. The key\-value pairs in this list are in the \fBbundle\&.*\fR namespace (see (...) Strangely, the --file above is rendered correctly, but the bundle.* below not. I do not know TROFF to assess what is going on. Has '*' a special behavior in a bold span? JN

gitgitgadget · 2025-04-05T11:02:43Z

Documentation/git-mv.adoc

@@ -9,15 +9,13 @@ git-mv - Move or rename a file, a directory, or a symlink
 SYNOPSIS


On the Git mailing list, Martin Ågren wrote (reply to this):

On Sun, 30 Mar 2025 at 19:16, Jean-Noël Avila via GitGitGadget <[email protected]> wrote: > [verse] > -'git mv' [<options>] <source>... <destination> > +'git mv' [-v] [-f] [-n] [-k] <source> <destination> > +'git mv' [-v] [-f] [-n] [-k] <source> ... <destination-directory> Shouldn't "..." be tucked with the preceding "<source>", i.e., "<source>..." as it was in the original? > DESCRIPTION > ----------- > Move or rename a file, directory, or symlink. > > - git mv [-v] [-f] [-n] [-k] <source> <destination> > - git mv [-v] [-f] [-n] [-k] <source> ... <destination-directory> > - This is where "<source> ..." comes from. You moved these lines up. Good. But I do think we want "<source>..."? Martin

gitgitgadget · 2025-04-07T22:33:16Z

This branch is now known as ja/doc-reset-mv-rm-markup-updates.

gitgitgadget · 2025-04-07T22:33:17Z

This patch series was integrated into seen via git@e5cc963.

gitgitgadget · 2025-04-08T15:44:40Z

This patch series was integrated into seen via git@79ed5a8.

gitgitgadget · 2025-04-08T20:28:24Z

This patch series was integrated into seen via git@0d747b8.

gitgitgadget · 2025-04-11T15:47:04Z

This patch series was integrated into seen via git@30174dc.

gitgitgadget · 2025-04-11T23:02:57Z

There was a status update in the "Cooking" section about the branch ja/doc-reset-mv-rm-markup-updates on the Git mailing list:

Expecting a reroll.
cf. <CAN0heSodC8_Uwg_Lw31rtkdLfOEDyGg=iE0gb1TRrUWQEynT+w@mail.gmail.com>
cf. <[email protected]>
source: <[email protected]>

- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <[email protected]>

The synopsis analysis logic was not able to handle backslashes and stars which are used in the synopsis of the git-rm command. This patch fixes the issue by updating the regular expression used to match the keywords. Signed-off-by: Jean-Noël Avila <[email protected]>

- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Signed-off-by: Jean-Noël Avila <[email protected]>

This also entails changing the help output for the command to match the new synopsis. Signed-off-by: Jean-Noël Avila <[email protected]>

- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace - Use _<placeholder>_ instead of <placeholder> in the description - Use `backticks` for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans. Unfortunately, there's an inconsistency in the synopsis style, where the ellipsis is used to indicate that the option can be repeated, but it can also be used in Git's three-dot notation to indicate a range of commits. The rendering engine will not be able to distinguish between these two cases. Signed-off-by: Jean-Noël Avila <[email protected]>

The processing of triple dot notation is tricky because it can be mis-interpreted as an ellipsis. The special processing of the ellipsis is now complete and takes into account the case of `git-mv <source>... <dest>` Signed-off-by: Jean-Noël Avila <[email protected]>

This rule was already implicitely applied in the converted man pages, so let's state it loudly. Signed-off-by: Jean-Noël Avila <[email protected]>

jnavila · 2025-04-12T12:19:58Z

/submit

gitgitgadget · 2025-04-12T12:21:10Z

Submitted as [email protected]

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1896/jnavila/doc_git_reset-v2

To fetch this version to local tag pr-1896/jnavila/doc_git_reset-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1896/jnavila/doc_git_reset-v2

jnavila force-pushed the doc_git_reset branch from a7f97d2 to 4887567 Compare March 30, 2025 15:41

jnavila changed the title ~~doc: convert git-reset to new documentation format~~ doc: convert git-reset, git-rm and git-mv to new documentation format Mar 30, 2025

gitgitgadget bot added the seen label Apr 1, 2025

gitgitgadget bot reviewed Apr 4, 2025

View reviewed changes

gitgitgadget bot reviewed Apr 5, 2025

View reviewed changes

jnavila force-pushed the doc_git_reset branch from 2bd9123 to 0355c58 Compare April 12, 2025 09:30

jnavila added 6 commits April 12, 2025 17:55

doc: move synopsis git-mv commands in the synopsis section

2a12973

This also entails changing the help output for the command to match the new synopsis. Signed-off-by: Jean-Noël Avila <[email protected]>

jnavila force-pushed the doc_git_reset branch from 0355c58 to 2ddce76 Compare April 12, 2025 09:55

doc: add markup for characters in Guidelines

2690f84

This rule was already implicitely applied in the converted man pages, so let's state it loudly. Signed-off-by: Jean-Noël Avila <[email protected]>

jnavila force-pushed the doc_git_reset branch from db0ef65 to 2690f84 Compare April 12, 2025 12:13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

jnavila commented Mar 28, 2025 •

edited

Loading

jnavila commented Mar 30, 2025

gitgitgadget bot commented Mar 30, 2025

gitgitgadget bot commented Apr 1, 2025

gitgitgadget bot Apr 4, 2025

gitgitgadget bot commented Apr 4, 2025

gitgitgadget bot Apr 4, 2025

gitgitgadget bot Apr 12, 2025

gitgitgadget bot Apr 5, 2025

gitgitgadget bot commented Apr 7, 2025

gitgitgadget bot commented Apr 7, 2025

gitgitgadget bot commented Apr 8, 2025

gitgitgadget bot commented Apr 8, 2025

gitgitgadget bot commented Apr 11, 2025

gitgitgadget bot commented Apr 11, 2025

jnavila commented Apr 12, 2025

gitgitgadget bot commented Apr 12, 2025

		@@ -7,23 +7,23 @@ git-reset - Reset current HEAD to the specified state

		@@ -43,7 +43,7 @@ ifdef::doctype-book[]
		endif::doctype-book[]

		@@ -9,15 +9,13 @@ git-mv - Move or rename a file, a directory, or a symlink
		SYNOPSIS

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

Are you sure you want to change the base?

doc: convert git-reset, git-rm and git-mv to new documentation format #1896

Conversation

jnavila commented Mar 28, 2025 • edited Loading

jnavila commented Mar 30, 2025

gitgitgadget bot commented Mar 30, 2025

gitgitgadget bot commented Apr 1, 2025

gitgitgadget bot Apr 4, 2025

Choose a reason for hiding this comment

gitgitgadget bot commented Apr 4, 2025

gitgitgadget bot Apr 4, 2025

Choose a reason for hiding this comment

gitgitgadget bot Apr 12, 2025

Choose a reason for hiding this comment

gitgitgadget bot Apr 5, 2025

Choose a reason for hiding this comment

gitgitgadget bot commented Apr 7, 2025

gitgitgadget bot commented Apr 7, 2025

gitgitgadget bot commented Apr 8, 2025

gitgitgadget bot commented Apr 8, 2025

gitgitgadget bot commented Apr 11, 2025

gitgitgadget bot commented Apr 11, 2025

jnavila commented Apr 12, 2025

gitgitgadget bot commented Apr 12, 2025

jnavila commented Mar 28, 2025 •

edited

Loading