Skip to content

doc: convert git log man page to new synopsis format #1933

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 9 commits into from
Closed

doc: convert git log man page to new synopsis format #1933

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
10ea4ad
doc: convert git-log to new documentation format
jnavila Jun 7, 2025
9b52a62
doc: git-log convert rev-list-description to new doc format
jnavila Jun 7, 2025
b0b2290
doc: git-log: convert line range options to new doc format
jnavila Jun 7, 2025
a4ac3ea
doc: git-log: convert line range format to new doc format
jnavila Jun 7, 2025
1eb897e
doc: git-log: convert rev list options to new doc format
jnavila Jun 7, 2025
b860561
doc: git-log: convert pretty options to new doc format
jnavila Jun 7, 2025
0d46154
doc: git-log: convert pretty formats to new doc format
jnavila Jun 7, 2025
207fc49
doc: git-log: convert diff options to new doc format
jnavila Jun 7, 2025
b51d362
doc: git-log: convert log config to new doc format
jnavila Jun 7, 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
2 changes: 1 addition & 1 deletion Documentation/asciidoc.conf.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ ifdef::doctype-book[]
endif::doctype-book[]

[literal-inlinemacro]
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}
{eval:re.sub(r'(&lt;[-a-zA-Z0-9.]+&gt;)', r'<emphasis>\1</emphasis>', re.sub(r'([\[\s|()>]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@\\\*\/_^\$%]+\.?)+|,)',r'\1<literal>\2</literal>', re.sub(r'(\.\.\.?)([^\]$.])', r'<literal>\1</literal>\2', macros.passthroughs[int(attrs['passtext'][1:-1])] if attrs['passtext'][1:-1].isnumeric() else attrs['passtext'][1:-1])))}

endif::backend-docbook[]

Expand Down
4 changes: 2 additions & 2 deletions Documentation/asciidoctor-extensions.rb.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ module Git
elsif type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$\.])/, '<literal>\1</literal>\2')
.gsub(/^\.\.\.?$/, '<literal>\0</literal>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@/_^\$\\\*%]+\.{0,2})+|,)}, '\1<literal>\2</literal>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<emphasis>\1</emphasis>')
else
open, close, supports_phrase = QUOTE_TAGS[type]
Expand Down Expand Up @@ -102,7 +102,7 @@ module Git
if node.type == :monospaced
node.text.gsub(/(\.\.\.?)([^\]$.])/, '<code>\1</code>\2')
.gsub(/^\.\.\.?$/, '<code>\0</code>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(%r{([\[\s|()>.]|^|\]|&gt;)(\.?([-a-zA-Z0-9:+=~@,/_^\$\\\*%]+\.{0,2})+)}, '\1<code>\2</code>')
.gsub(/(&lt;[-a-zA-Z0-9.]+&gt;)/, '<em>\1</em>')

else
Expand Down
86 changes: 46 additions & 40 deletions Documentation/git-log.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ git-log - Show commit logs

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 via GitGitGadget" <[email protected]> writes:

> 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.
>
> Signed-off-by: Jean-Noël Avila <[email protected]>
> ---
>  Documentation/git-log.adoc | 83 ++++++++++++++++++++------------------
>  1 file changed, 44 insertions(+), 39 deletions(-)

This hunk (lightly edited to shift contexts) ...

> ---no-decorate::
> ---decorate[=short|full|auto|no]::
> -	Print out the ref names of any commits that are shown. If 'short' is
> -	specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
> -	'refs/remotes/' will not be printed. If 'full' is specified, the
> -	full ref name (including prefix) will be printed. If 'auto' is
> -	specified, then if the output is going to a terminal, the ref names
> -	are shown as if 'short' were given, otherwise no ref names are
> -	shown. The option `--decorate` is short-hand for `--decorate=short`.
> -	Default to configuration value of `log.decorate` if configured,
> -	otherwise, `auto`.
> +`--no-decorate`::
> +`--decorate[=(short|full|auto|no)]`::
> +	Print out the ref names of any commits that are shown. Possible values
> +	are:
> ++
> +----
> +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
> +	`refs/remotes/` are not printed.
> +`full`;; the full ref name (including prefix) is printed.
> +`auto`:: if the output is going to a terminal, the ref names
> +	are shown as if `short` were given, otherwise no ref names are
> +	shown.
> +----
> ++
> +The option `--decorate` is short-hand for `--decorate=short`. Default to
> +configuration value of `log.decorate` if configured, otherwise, `auto`.

... does more than what the three-bullet list in the proposed log
message describes.  The result is certainly easier to follow and
more extensible to have these possible values in an enumerated list
than in a prose.

> +`--decorate-refs=<pattern>`::
> +`--decorate-refs-exclude=<pattern>`::
>  	For each candidate reference, do not use it for decoration if it
> -	matches any patterns given to `--decorate-refs-exclude` or if it
> -	doesn't match any of the patterns given to `--decorate-refs`. The
> +	matches any of _<pattern>_ given to `--decorate-refs-exclude` or if it
> +	doesn't match any of _<pattern>_ given to `--decorate-refs`. The

"any patterns" in the original may not be grammatical, but the
rewritten "any of _<pattern>_" does not sound grammatical, either.
"any of the _<pattern>_s"?  I dunno what the convention should be
when more than one <placeholder> instances have to be referenced.

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 Tuesday, 17 June 2025 01:02:11 CEST Junio C Hamano wrote:
> "Jean-Noël Avila via GitGitGadget" <[email protected]> writes:
> > 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.
> > 
> > Signed-off-by: Jean-Noël Avila <[email protected]>
> > ---
> > 
> >  Documentation/git-log.adoc | 83 ++++++++++++++++++++------------------
> >  1 file changed, 44 insertions(+), 39 deletions(-)
> 
> This hunk (lightly edited to shift contexts) ...
> 
> > ---no-decorate::
> > ---decorate[=short|full|auto|no]::
> > -	Print out the ref names of any commits that are shown. If 'short' 
is
> > -	specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
> > -	'refs/remotes/' will not be printed. If 'full' is specified, the
> > -	full ref name (including prefix) will be printed. If 'auto' is
> > -	specified, then if the output is going to a terminal, the ref names
> > -	are shown as if 'short' were given, otherwise no ref names are
> > -	shown. The option `--decorate` is short-hand for `--
decorate=short`.
> > -	Default to configuration value of `log.decorate` if configured,
> > -	otherwise, `auto`.
> > +`--no-decorate`::
> > +`--decorate[=(short|full|auto|no)]`::
> > +	Print out the ref names of any commits that are shown. Possible 
values
> > +	are:
> > ++
> > +----
> > +`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
> > +	`refs/remotes/` are not printed.
> > +`full`;; the full ref name (including prefix) is printed.
> > +`auto`:: if the output is going to a terminal, the ref names
> > +	are shown as if `short` were given, otherwise no ref names are
> > +	shown.
> > +----
> > ++
> > +The option `--decorate` is short-hand for `--decorate=short`. Default to
> > +configuration value of `log.decorate` if configured, otherwise, `auto`.
> 
> ... does more than what the three-bullet list in the proposed log
> message describes.  The result is certainly easier to follow and
> more extensible to have these possible values in an enumerated list
> than in a prose.

True. That may become a new rule too.

> 
> > +`--decorate-refs=<pattern>`::
> > 
> > +`--decorate-refs-exclude=<pattern>`::
> >  	For each candidate reference, do not use it for decoration if it
> > 
> > -	matches any patterns given to `--decorate-refs-exclude` or if it
> > -	doesn't match any of the patterns given to `--decorate-refs`. The
> > +	matches any of _<pattern>_ given to `--decorate-refs-exclude` or 
if it
> > +	doesn't match any of _<pattern>_ given to `--decorate-refs`. The
> 
> "any patterns" in the original may not be grammatical, but the
> rewritten "any of _<pattern>_" does not sound grammatical, either.
> "any of the _<pattern>_s"?  I dunno what the convention should be
> when more than one <placeholder> instances have to be referenced.

Good question for which I was more inclined to consider placeholders as 
invariant, even if the result may sound "ungrammatical". This also simplifies 
the translation process where the plural forms can be complicated in some 
languages.

SYNOPSIS
--------
[verse]
'git log' [<options>] [<revision-range>] [[--] <path>...]
[synopsis]
git log [<options>] [<revision-range>] [[--] <path>...]

DESCRIPTION
-----------
Expand All @@ -27,80 +27,86 @@ each commit introduces are shown.
OPTIONS
-------

--follow::
`--follow`::
Continue listing the history of a file beyond renames
(works only for a single file).

--no-decorate::
--decorate[=short|full|auto|no]::
Print out the ref names of any commits that are shown. If 'short' is
specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and
'refs/remotes/' will not be printed. If 'full' is specified, the
full ref name (including prefix) will be printed. If 'auto' is
specified, then if the output is going to a terminal, the ref names
are shown as if 'short' were given, otherwise no ref names are
shown. The option `--decorate` is short-hand for `--decorate=short`.
Default to configuration value of `log.decorate` if configured,
otherwise, `auto`.

--decorate-refs=<pattern>::
--decorate-refs-exclude=<pattern>::
`--no-decorate`::
`--decorate[=(short|full|auto|no)]`::
Print out the ref names of any commits that are shown. Possible values
are:
+
----
`short`;; the ref name prefixes `refs/heads/`, `refs/tags/` and
`refs/remotes/` are not printed.
`full`;; the full ref name (including prefix) is printed.
`auto`:: if the output is going to a terminal, the ref names
are shown as if `short` were given, otherwise no ref names are
shown.
----
+
The option `--decorate` is short-hand for `--decorate=short`. Default to
configuration value of `log.decorate` if configured, otherwise, `auto`.

`--decorate-refs=<pattern>`::
`--decorate-refs-exclude=<pattern>`::
For each candidate reference, do not use it for decoration if it
matches any patterns given to `--decorate-refs-exclude` or if it
doesn't match any of the patterns given to `--decorate-refs`. The
`log.excludeDecoration` config option allows excluding refs from
matches any of the _<pattern>_ parameters given to
`--decorate-refs-exclude` or if it doesn't match any of the
_<pattern>_ parameters given to `--decorate-refs`.
The `log.excludeDecoration` config option allows excluding refs from
the decorations, but an explicit `--decorate-refs` pattern will
override a match in `log.excludeDecoration`.
+
If none of these options or config settings are given, then references are
used as decoration if they match `HEAD`, `refs/heads/`, `refs/remotes/`,
`refs/stash/`, or `refs/tags/`.

--clear-decorations::
`--clear-decorations`::
When specified, this option clears all previous `--decorate-refs`
or `--decorate-refs-exclude` options and relaxes the default
decoration filter to include all references. This option is
assumed if the config value `log.initialDecorationSet` is set to
`all`.

--source::
`--source`::
Print out the ref name given on the command line by which each
commit was reached.

--[no-]mailmap::
--[no-]use-mailmap::
`--[no-]mailmap`::
`--[no-]use-mailmap`::
Use mailmap file to map author and committer names and email
addresses to canonical real names and email addresses. See
linkgit:git-shortlog[1].

--full-diff::
`--full-diff`::
Without this flag, `git log -p <path>...` shows commits that
touch the specified paths, and diffs about the same specified
paths. With this, the full diff is shown for commits that touch
the specified paths; this means that "<path>..." limits only
the specified paths; this means that "`<path>...`" limits only
commits, and doesn't limit diff for those commits.
+
Note that this affects all diff-based output types, e.g. those
produced by `--stat`, etc.

--log-size::
Include a line ``log size <number>'' in the output for each commit,
where <number> is the length of that commit's message in bytes.
`--log-size`::
Include a line `log size <number>` in the output for each commit,
where _<number>_ is the length of that commit's message in bytes.
Intended to speed up tools that read log messages from `git log`
output by allowing them to allocate space in advance.

include::line-range-options.adoc[]

<revision-range>::
_<revision-range>_::
Show only commits in the specified revision range. When no
<revision-range> is specified, it defaults to `HEAD` (i.e. the
_<revision-range>_ is specified, it defaults to `HEAD` (i.e. the
whole history leading to the current commit). `origin..HEAD`
specifies all the commits reachable from the current commit
(i.e. `HEAD`), but not from `origin`. For a complete list of
ways to spell <revision-range>, see the 'Specifying Ranges'
ways to spell _<revision-range>_, see the 'Specifying Ranges'
section of linkgit:gitrevisions[7].

[--] <path>...::
`[--] <path>...`::
Show only commits that are enough to explain how the files
that match the specified paths came to be. See 'History
Simplification' below for details and other simplification
Expand Down Expand Up @@ -145,14 +151,14 @@ EXAMPLES

`git log --since="2 weeks ago" -- gitk`::

Show the changes during the last two weeks to the file 'gitk'.
Show the changes during the last two weeks to the file `gitk`.
The `--` is necessary to avoid confusion with the *branch* named
'gitk'
`gitk`

`git log --name-status release..test`::

Show the commits that are in the "test" branch but not yet
in the "release" branch, along with the list of paths
Show the commits that are in the "`test`" branch but not yet
in the "`release`" branch, along with the list of paths
each commit modifies.

`git log --follow builtin/rev-list.c`::
Expand All @@ -164,7 +170,7 @@ EXAMPLES
`git log --branches --not --remotes=origin`::

Shows all commits that are in any of local branches but not in
any of remote-tracking branches for 'origin' (what you have that
any of remote-tracking branches for `origin` (what you have that
origin doesn't).

`git log master --not --remotes=*/master`::
Expand Down Expand Up @@ -200,11 +206,11 @@ CONFIGURATION
See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
for settings related to diff generation.

format.pretty::
`format.pretty`::
Default for the `--format` option. (See 'Pretty Formats' above.)
Defaults to `medium`.

i18n.logOutputEncoding::
`i18n.logOutputEncoding`::
Encoding to use when displaying logs. (See 'Discussion' above.)
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
Expand Down
26 changes: 13 additions & 13 deletions Documentation/line-range-format.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,30 @@
'<start>' and '<end>' can take one of these forms:
_<start>_ and _<end>_ can take one of these forms:

- number
- _<number>_
+
If '<start>' or '<end>' is a number, it specifies an
If _<start>_ or _<end>_ is a number, it specifies an
absolute line number (lines count from 1).
+

- `/regex/`
- `/<regex>/`
+
This form will use the first line matching the given
POSIX regex. If '<start>' is a regex, it will search from the end of
POSIX _<regex>_. If _<start>_ is a regex, it will search from the end of
the previous `-L` range, if any, otherwise from the start of file.
If '<start>' is `^/regex/`, it will search from the start of file.
If '<end>' is a regex, it will search
starting at the line given by '<start>'.
If _<start>_ is `^/<regex>/`, it will search from the start of file.
If _<end>_ is a regex, it will search starting at the line given by
_<start>_.
+

- +offset or -offset
- `+<offset>` or `-<offset>`
+
This is only valid for '<end>' and will specify a number
of lines before or after the line given by '<start>'.
This is only valid for _<end>_ and will specify a number
of lines before or after the line given by _<start>_.

+
If `:<funcname>` is given in place of '<start>' and '<end>', it is a
If `:<funcname>` is given in place of _<start>_ and _<end>_, it is a
regular expression that denotes the range from the first funcname line
that matches '<funcname>', up to the next funcname line. `:<funcname>`
that matches _<funcname>_, up to the next funcname line. `:<funcname>`
searches from the end of the previous `-L` range, if any, otherwise
from the start of file. `^:<funcname>` searches from the start of
file. The function names are determined in the same way as `git diff`
Expand Down
10 changes: 5 additions & 5 deletions Documentation/line-range-options.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
-L<start>,<end>:<file>::
-L:<funcname>:<file>::
`-L<start>,<end>:<file>`::
`-L:<funcname>:<file>`::

Trace the evolution of the line range given by '<start>,<end>',
or by the function name regex '<funcname>', within the '<file>'. You may
Trace the evolution of the line range given by `<start>,<end>`,
or by the function name regex _<funcname>_, within the _<file>_. You may
not give any pathspec limiters. This is currently limited to
a walk starting from a single revision, i.e., you may only
give zero or one positive revision arguments, and
'<start>' and '<end>' (or '<funcname>') must exist in the starting revision.
_<start>_ and _<end>_ (or _<funcname>_) must exist in the starting revision.
You can specify this option more than once. Implies `--patch`.
Patch output can be suppressed using `--no-patch`, but other diff formats
(namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`,
Expand Down
Loading