+
Skip to content

doc: convert git-stash, git tag and git worktree to synopis style #1969

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
+280 −253
Closed

doc: convert git-stash, git tag and git worktree to synopis style #1969

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3f3e5a8
doc: convert git-stash.adoc to synopis style
jnavila Sep 7, 2025
9d23142
doc: convert git tag to synopsis style
jnavila Oct 5, 2025
c62b65c
doc: convert git worktree to synopsis style
jnavila Oct 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 19 additions & 10 deletions Documentation/config/stash.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,28 @@
stash.index::
ifndef::git-stash[]
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, "Kristoffer Haugsbakk" wrote (reply to this):

On Sun, Oct 5, 2025, at 23:11, Jean-Noël Avila via GitGitGadget wrote:
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> - 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.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/config/stash.adoc |  29 ++++---
>  Documentation/git-stash.adoc    | 134 ++++++++++++++++----------------
>  2 files changed, 85 insertions(+), 78 deletions(-)
>
> diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
> index e556105a15..7fc32027f7 100644
> --- a/Documentation/config/stash.adoc
> +++ b/Documentation/config/stash.adoc
> @@ -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`.

> +endif::git-stash[]
> +
> +ifdef::git-stash[]
> +:see-show:
> +endif::git-stash[]
>[snip]

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Le 10/10/2025 à 01:48, Kristoffer Haugsbakk a écrit :
> On Sun, Oct 5, 2025, at 23:11, Jean-Noël Avila via GitGitGadget wrote:
>> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>>
>> - 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.
>>
>> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>> ---
>>  Documentation/config/stash.adoc |  29 ++++---
>>  Documentation/git-stash.adoc    | 134 ++++++++++++++++----------------
>>  2 files changed, 85 insertions(+), 78 deletions(-)
>>
>> diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
>> index e556105a15..7fc32027f7 100644
>> --- a/Documentation/config/stash.adoc
>> +++ b/Documentation/config/stash.adoc
>> @@ -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`.

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.

> 
>> +endif::git-stash[]
>> +
>> +ifdef::git-stash[]
>> +:see-show:
>> +endif::git-stash[]
>> [snip]

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Jean-Noël Avila <jn.avila@free.fr> writes:

>>> diff --git a/Documentation/config/stash.adoc b/Documentation/config/stash.adoc
>>> index e556105a15..7fc32027f7 100644
>>> --- a/Documentation/config/stash.adoc
>>> +++ b/Documentation/config/stash.adoc
>>> @@ -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`.
>
> 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?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

On Friday, 10 October 2025 17:52:59 CEST Junio C Hamano wrote:
> Jean-Noël Avila <jn.avila@free.fr> writes:
> >>> diff --git a/Documentation/config/stash.adoc b/Documentation/config/
stash.adoc
> >>> index e556105a15..7fc32027f7 100644
> >>> --- a/Documentation/config/stash.adoc
> >>> +++ b/Documentation/config/stash.adoc
> >>> @@ -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`.
> > 
> > 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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

Jean-Noël AVILA <jn.avila@free.fr> writes:

>> > 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.

OK.  Let me make sure that I did not mark the topic as "on hold".

Thanks.

: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}
22 changes: 14 additions & 8 deletions Documentation/config/tag.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
14 changes: 7 additions & 7 deletions Documentation/config/worktree.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
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
set to true, `worktree add` tries to find a remote-tracking
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.
Loading
Loading
点击 这是indexloc提供的php浏览器服务，不要输入任何密码和下载