doc: convert git-stash, git tag and git worktree to synopis style
cover doc: convert git-stash, git tag and git worktree to synopis style
* Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
* Use instead of in the description
* Use backticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
Also add the CONFIGURATION section when it is missing and do not refer to the man page in the description of settings when this list is included in the manual page.
Jean-Noël Avila (3):
doc: convert git-stash.adoc to synopis style
doc: convert git tag to synopsis style
doc: convert git worktree to synopsis style
Documentation/config/stash.adoc | 29 +++-- Documentation/config/tag.adoc | 22 ++-- Documentation/config/worktree.adoc | 14 +-- Documentation/git-stash.adoc | 134 +++++++++++----------- Documentation/git-tag.adoc | 173 +++++++++++++++-------------- Documentation/git-worktree.adoc | 161 ++++++++++++++------------- 6 files changed, 280 insertions(+), 253 deletions(-)
base-commit: 5099f64a82ccc80f3c6567589bfeb5e9a1b9fd6b
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1969%2Fjnavila%2Fdoc_git_stash-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1969/jnavila/doc_git_stash-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1969
Signature · 1 line
gitgitgadget
PATCH 1/3 doc: convert git-stash.adoc to synopis style
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use backticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
Also do not refer to the man page in the description of settings when this description is already in the man page.
--- Documentation/config/stash.adoc | 29 ++++--- Documentation/git-stash.adoc | 134 ++++++++++++++++---------------- 2 files changed, 85 insertions(+), 78 deletions(-)
Documentation/config/stash.adoc +19 -10
@@ -1,19 +1,28 @@ -stash.index:: +ifndef::git-stash[] +:see-show: See the description of the 'show' command in linkgit:git-stash[1]. +endif::git-stash[] + +ifdef::git-stash[] +:see-show: +endif::git-stash[] + +`stash.index`:: If this is set to true, `git stash apply` and `git stash pop` will - behave as if `--index` was supplied. Defaults to false. See the - descriptions in linkgit:git-stash[1]. + behave as if `--index` was supplied. Defaults to false. +ifndef::git-stash[] +See the descriptions in linkgit:git-stash[1]. +endif::git-stash[] -stash.showIncludeUntracked:: +`stash.showIncludeUntracked`:: If this is set to true, the `git stash show` command will show - the untracked files of a stash entry. Defaults to false. See - the description of the 'show' command in linkgit:git-stash[1]. + the untracked files of a stash entry. Defaults to false. {see-show} -stash.showPatch:: +`stash.showPatch`:: If this is set to true, the `git stash show` command without an option will show the stash entry in patch form. Defaults to false. - See the description of the 'show' command in linkgit:git-stash[1]. + {see-show} -stash.showStat:: +`stash.showStat`:: If this is set to true, the `git stash show` command without an option will show a diffstat of the stash entry. Defaults to true. - See the description of the 'show' command in linkgit:git-stash[1]. + {see-show}
Documentation/git-stash.adoc +66 -68
320 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH 2/3 doc: convert git tag to synopsis style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use backticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
Also add the config section in the manual page and do not refer to the man page in the description of settings when this description is already in the man page.
--- Documentation/config/tag.adoc | 22 +++-- Documentation/git-tag.adoc | 173 ++++++++++++++++++---------------- 2 files changed, 104 insertions(+), 91 deletions(-)
Documentation/config/tag.adoc +14 -8
@@ -1,17 +1,23 @@ -tag.forceSignAnnotated:: +`tag.forceSignAnnotated`:: A boolean to specify whether annotated tags created should be GPG signed. If `--annotate` is specified on the command line, it takes precedence over this option. -tag.sort:: - This variable controls the sort ordering of tags when displayed by - linkgit:git-tag[1]. Without the "--sort=<value>" option provided, the - value of this variable will be used as the default. +`tag.sort`:: +ifdef::git-tag[] +This variable controls the sort ordering of tags when displayed by `git-tag`. +endif::git-tag[] +ifndef::git-tag[] +This variable controls the sort ordering of tags when displayed by +linkgit:git-tag[1]. +endif::git-tag[] +Without the `--sort=<value>` option provided, the value of this variable will +be used as the default. -tag.gpgSign:: +`tag.gpgSign`:: A boolean to specify whether all tags should be GPG signed. Use of this option when running in an automated script can result in a large number of tags being signed. It is therefore - convenient to use an agent to avoid typing your gpg passphrase + convenient to use an agent to avoid typing your GPG passphrase several times. Note that this option doesn't affect tag signing - behavior enabled by "-u <keyid>" or "--local-user=<keyid>" options. + behavior enabled by `-u <keyid>` or `--local-user=<keyid>` options.
Documentation/git-tag.adoc +90 -83
318 lines not on this page · raw message
Signature · 1 line
gitgitgadget
PATCH 3/3 doc: convert git worktree to synopsis style
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Use backticks for keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.
Also add the config section in the manual page and do not refer to the man page in the description of settings when this description is already in the man page.
--- Documentation/config/worktree.adoc | 14 +-- Documentation/git-worktree.adoc | 161 +++++++++++++++-------------- 2 files changed, 91 insertions(+), 84 deletions(-)
Documentation/config/worktree.adoc +7 -7
@@ -1,4 +1,4 @@ -worktree.guessRemote:: +`worktree.guessRemote`:: If no branch is specified and neither `-b` nor `-B` nor `--detach` is used, then `git worktree add` defaults to creating a new branch from HEAD. If `worktree.guessRemote` is
@@ -6,14 +6,14 @@ worktree.guessRemote:: branch whose name uniquely matches the new branch name. If such a branch exists, it is checked out and set as "upstream" for the new branch. If no such match can be found, it falls - back to creating a new branch from the current HEAD. + back to creating a new branch from the current `HEAD`. -worktree.useRelativePaths:: - Link worktrees using relative paths (when "true") or absolute - paths (when "false"). This is particularly useful for setups +`worktree.useRelativePaths`:: + Link worktrees using relative paths (when "`true`") or absolute + paths (when "`false`"). This is particularly useful for setups where the repository and worktrees may be moved between - different locations or environments. Defaults to "false". + different locations or environments. Defaults to "`false`". + -Note that setting `worktree.useRelativePaths` to "true" implies enabling the +Note that setting `worktree.useRelativePaths` to "`true`" implies enabling the `extensions.relativeWorktrees` config (see linkgit:git-config[1]), thus making it incompatible with older versions of Git.
Documentation/git-worktree.adoc +84 -77
325 lines not on this page · raw message
Signature · 1 line
gitgitgadget
Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
In reply to Jean-Noël Avila via GitGitGadgetQuoted 23 lines · Jean-Noël Avila via GitGitGadget
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Usebackticksfor keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.Also do not refer to the man page in the description of settings when this description is already in the man page.
Signed-off-by Jean-Noël Avila <[email protected]>--- Documentation/config/stash.adoc | 29 ++++--- Documentation/git-stash.adoc | 134 ++++++++++++++++---------------- 2 files changed, 85 insertions(+), 78 deletions(-)Documentation/config/stash.adoc +0
-0
Documentation/config/stash.adoc line 2
Quoted 3 lines
Documentation/config/stash.adoc +2
-1@@ -1,19 +1,28 @@ -stash.index:: +ifndef::git-stash[] +:see-show: See the description of the 'show' command in linkgit:git-stash[1].
Okay, here you use 'show' and not show because this conditional attribute will pass on show and render it as such, not as inline-verbatim “show”. Bare 'show' is indeed better than bare show.
Quoted 6 lines
Documentation/config/stash.adoc +5
-0+endif::git-stash[] + +ifdef::git-stash[] +:see-show: +endif::git-stash[]
Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Le 10/10/2025 à 01:48, Kristoffer Haugsbakk a écrit :
Quoted 19 lines · Jean-Noël Avila via GitGitGadget
Quoted 18 lines
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
- Switch the synopsis to a synopsis block which will automatically format placeholders in italics and keywords in monospace
- Use _<placeholder>_ instead of <placeholder> in the description
- Usebackticksfor keywords and more complex option descriptions. The new rendering engine will apply synopsis rules to these spans.Also do not refer to the man page in the description of settings when this description is already in the man page.
Signed-off-by Jean-Noël Avila <[email protected]>--- Documentation/config/stash.adoc | 29 ++++--- Documentation/git-stash.adoc | 134 ++++++++++++++++---------------- 2 files changed, 85 insertions(+), 78 deletions(-)
Quoted 12 lines
Documentation/config/stash.adoc line 2
Quoted 8 lines
Documentation/config/stash.adoc +2
-1@@ -1,19 +1,28 @@ -stash.index:: +ifndef::git-stash[] +:see-show: See the description of the 'show' command in linkgit:git-stash[1].Okay, here you use 'show' and not
showbecause this conditional attribute will pass onshowand render it as such, not as inline-verbatim “show”. Bare 'show' is indeed better than bareshow.
TBH I did not spot the issue when I did this. I wasn't aware that Asciidoc does not automatically handle inline formatting in attributes. But it seems we can force it. This "show" keyword should definitely be inline verbatim.
Wil try and reroll.
Quoted 7 lines
Quoted 7 lines
Documentation/config/stash.adoc +5
-0+endif::git-stash[] + +ifdef::git-stash[] +:see-show: +endif::git-stash[]
Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Quoted 13 lines · Jean-Noël Avila
Quoted 4 lines
Quoted 4 lines
Documentation/config/stash.adoc +0
-0Quoted 8 lines
Documentation/config/stash.adoc line 2
Quoted 4 lines
Documentation/config/stash.adoc +2
-1@@ -1,19 +1,28 @@ -stash.index:: +ifndef::git-stash[] +:see-show: See the description of the 'show' command in linkgit:git-stash[1].Okay, here you use 'show' and not
showbecause this conditional attribute will pass onshowand render it as such, not as inline-verbatim “show”. Bare 'show' is indeed better than bareshow.
Quoted 6 lines
TBH I did not spot the issue when I did this. I wasn't aware that Asciidoc does not automatically handle inline formatting in attributes. But it seems we can force it. This "show" keyword should definitely be inline verbatim.
Wil try and reroll.
This is already in 'next', isn't it, though?
Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Quoted 2 lines · On Friday, 10 October 2025 17:52:59 CEST Junio C Hamano wrote:
Quoted 1 line · Jean-Noël Avila
Quoted 1 line
Documentation/config/
Quoted 1 line
Documentation/config/ renamed from Documentation/config/stash.adoc +0
-0
stash.adoc
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Documentation/config/stash.adoc line 2
Quoted 7 lines
index
e556105a15..7fc32027f7100644Documentation/config/stash.adoc +2
-1@@ -1,19 +1,28 @@ -stash.index:: +ifndef::git-stash[] +:see-show: See the description of the 'show' command in linkgit:git-
stash[1].
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines
Okay, here you use 'show' and not
showbecause this conditional attribute will pass onshowand render it as such, not as inline-verbatim “show”. Bare 'show' is indeed better than bareshow.
Quoted 8 lines
Quoted 6 lines
TBH I did not spot the issue when I did this. I wasn't aware that Asciidoc does not automatically handle inline formatting in attributes. But it seems we can force it. This "show" keyword should definitely be inline verbatim.
Wil try and reroll.
This is already in 'next', isn't it, though?
That's fine. I couldn't come up with a substitution scheme that would work correctly for both asciidoc.py and asciidoctor.
So let's just let this patch as it is and recall that attributes are not a panacea.
Re: [PATCH 1/3] doc: convert git-stash.adoc to synopis style
Quoted 9 lines · Jean-Noël AVILA
Quoted 3 lines
Quoted 1 line
Wil try and reroll.
This is already in 'next', isn't it, though?
That's fine. I couldn't come up with a substitution scheme that would work correctly for both
asciidoc.pyand asciidoctor.So let's just let this patch as it is and recall that attributes are not a panacea.
OK. Let me make sure that I did not mark the topic as "on hold".
Thanks.