* [PATCH 1/4] doc: convert git-difftool manual page to synopsis style
2026-04-04 17:12 [PATCH 0/4] Doc difftool Jean-Noël Avila via GitGitGadget
@ 2026-04-04 17:12 ` Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 2/4] doc: convert git-range-diff " Jean-Noël Avila via GitGitGadget
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2026-04-04 17:12 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
* convert commands to synopsis style
* use _<placeholder>_ for arguments
* fix conditional text to sentence limits
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/config/difftool.adoc | 24 ++++-----
Documentation/config/mergetool.adoc | 8 +--
Documentation/git-difftool.adoc | 80 ++++++++++++++---------------
3 files changed, 56 insertions(+), 56 deletions(-)
diff --git a/Documentation/config/difftool.adoc b/Documentation/config/difftool.adoc
index 4f7d40ce24..1b8d483813 100644
--- a/Documentation/config/difftool.adoc
+++ b/Documentation/config/difftool.adoc
@@ -1,43 +1,43 @@
-diff.tool::
+`diff.tool`::
Controls which diff tool is used by linkgit:git-difftool[1].
This variable overrides the value configured in `merge.tool`.
The list below shows the valid built-in values.
Any other value is treated as a custom diff tool and requires
- that a corresponding difftool.<tool>.cmd variable is defined.
+ that a corresponding `difftool.<tool>.cmd` variable is defined.
-diff.guitool::
+`diff.guitool`::
Controls which diff tool is used by linkgit:git-difftool[1] when
- the -g/--gui flag is specified. This variable overrides the value
+ the `-g`/`--gui` flag is specified. This variable overrides the value
configured in `merge.guitool`. The list below shows the valid
built-in values. Any other value is treated as a custom diff tool
- and requires that a corresponding difftool.<guitool>.cmd variable
+ and requires that a corresponding `difftool.<guitool>.cmd` variable
is defined.
include::{build_dir}/mergetools-diff.adoc[]
-difftool.<tool>.cmd::
+`difftool.<tool>.cmd`::
Specify the command to invoke the specified diff tool.
The specified command is evaluated in shell with the following
- variables available: 'LOCAL' is set to the name of the temporary
- file containing the contents of the diff pre-image and 'REMOTE'
+ variables available: `LOCAL` is set to the name of the temporary
+ file containing the contents of the diff pre-image and `REMOTE`
is set to the name of the temporary file containing the contents
of the diff post-image.
+
See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
-difftool.<tool>.path::
+`difftool.<tool>.path`::
Override the path for the given tool. This is useful in case
your tool is not in the PATH.
-difftool.trustExitCode::
+`difftool.trustExitCode`::
Exit difftool if the invoked diff tool returns a non-zero exit status.
+
See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
-difftool.prompt::
+`difftool.prompt`::
Prompt before each invocation of the diff tool.
-difftool.guiDefault::
+`difftool.guiDefault`::
Set `true` to use the `diff.guitool` by default (equivalent to specifying
the `--gui` argument), or `auto` to select `diff.guitool` or `diff.tool`
depending on the presence of a `DISPLAY` environment variable value. The
diff --git a/Documentation/config/mergetool.adoc b/Documentation/config/mergetool.adoc
index 7064f5a462..7afdcad92b 100644
--- a/Documentation/config/mergetool.adoc
+++ b/Documentation/config/mergetool.adoc
@@ -52,13 +52,13 @@
if `merge.tool` is configured as _<variant>_), Git will consult
`mergetool.<variant>.layout` to determine the tool's layout. If the
variant-specific configuration is not available, `vimdiff` ' s is used as
- fallback. If that too is not available, a default layout with 4 windows
- will be used. To configure the layout, see the 'BACKEND SPECIFIC HINTS'
+ fallback. If that too is not available, a default layout with 4 windows
+ will be used.
ifdef::git-mergetool[]
- section.
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section.
endif::[]
ifndef::git-mergetool[]
- section in linkgit:git-mergetool[1].
+To configure the layout, see the 'BACKEND SPECIFIC HINTS' section in linkgit:git-mergetool[1].
endif::[]
`mergetool.hideResolved`::
diff --git a/Documentation/git-difftool.adoc b/Documentation/git-difftool.adoc
index 064bc68347..dd7cacf95e 100644
--- a/Documentation/git-difftool.adoc
+++ b/Documentation/git-difftool.adoc
@@ -7,64 +7,64 @@ git-difftool - Show changes using common diff tools
SYNOPSIS
--------
-[verse]
-'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...]
+[synopsis]
+git difftool [<options>] [<commit> [<commit>]] [--] [<path>...]
DESCRIPTION
-----------
-'git difftool' is a Git command that allows you to compare and edit files
-between revisions using common diff tools. 'git difftool' is a frontend
-to 'git diff' and accepts the same options and arguments. See
+`git difftool` is a Git command that allows you to compare and edit files
+between revisions using common diff tools. `git difftool` is a frontend
+to `git diff` and accepts the same options and arguments. See
linkgit:git-diff[1].
OPTIONS
-------
--d::
---dir-diff::
+`-d`::
+`--dir-diff`::
Copy the modified files to a temporary location and perform
a directory diff on them. This mode never prompts before
launching the diff tool.
--y::
---no-prompt::
+`-y`::
+`--no-prompt`::
Do not prompt before launching a diff tool.
---prompt::
+`--prompt`::
Prompt before each invocation of the diff tool.
This is the default behaviour; the option is provided to
override any configuration settings.
---rotate-to=<file>::
- Start showing the diff for the given path,
+`--rotate-to=<file>`::
+ Start showing the diff for _<file>_,
the paths before it will move to the end and output.
---skip-to=<file>::
- Start showing the diff for the given path, skipping all
+`--skip-to=<file>`::
+ Start showing the diff for _<file>_, skipping all
the paths before it.
--t <tool>::
---tool=<tool>::
- Use the diff tool specified by <tool>. Valid values include
+`-t <tool>`::
+`--tool=<tool>`::
+ Use the diff tool specified by _<tool>_. Valid values include
emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help`
- for the list of valid <tool> settings.
+ for the list of valid _<tool>_ settings.
+
-If a diff tool is not specified, 'git difftool'
+If a diff tool is not specified, `git difftool`
will use the configuration variable `diff.tool`. If the
-configuration variable `diff.tool` is not set, 'git difftool'
+configuration variable `diff.tool` is not set, `git difftool`
will pick a suitable default.
+
You can explicitly provide a full path to the tool by setting the
configuration variable `difftool.<tool>.path`. For example, you
can configure the absolute path to kdiff3 by setting
-`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the
+`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the
tool is available in PATH.
+
Instead of running one of the known diff tools,
-'git difftool' can be customized to run an alternative program
+`git difftool` can be customized to run an alternative program
by specifying the command line to invoke in a configuration
variable `difftool.<tool>.cmd`.
+
-When 'git difftool' is invoked with this tool (either through the
+When `git difftool` is invoked with this tool (either through the
`-t` or `--tool` option or the `diff.tool` configuration variable)
the configured command line will be invoked with the following
variables available: `$LOCAL` is set to the name of the temporary
@@ -74,30 +74,30 @@ of the diff post-image. `$MERGED` is the name of the file which is
being compared. `$BASE` is provided for compatibility
with custom merge tool commands and has the same value as `$MERGED`.
---tool-help::
+`--tool-help`::
Print a list of diff tools that may be used with `--tool`.
---symlinks::
---no-symlinks::
- 'git difftool''s default behavior is to create symlinks to the
+`--symlinks`::
+`--no-symlinks`::
+ `git difftool`'s default behavior is to create symlinks to the
working tree when run in `--dir-diff` mode and the right-hand
side of the comparison yields the same content as the file in
the working tree.
+
-Specifying `--no-symlinks` instructs 'git difftool' to create copies
+Specifying `--no-symlinks` instructs `git difftool` to create copies
instead. `--no-symlinks` is the default on Windows.
--x <command>::
---extcmd=<command>::
+`-x <command>`::
+`--extcmd=<command>`::
Specify a custom command for viewing diffs.
- 'git-difftool' ignores the configured defaults and runs
+ `git-difftool` ignores the configured defaults and runs
`<command> $LOCAL $REMOTE` when this option is specified.
Additionally, `$BASE` is set in the environment.
--g::
---gui::
---no-gui::
- When 'git-difftool' is invoked with the `-g` or `--gui` option
+`-g`::
+`--gui`::
+`--no-gui`::
+ When `git-difftool` is invoked with the `-g` or `--gui` option
the default diff tool will be read from the configured
`diff.guitool` variable instead of `diff.tool`. This may be
selected automatically using the configuration variable
@@ -106,20 +106,20 @@ instead. `--no-symlinks` is the default on Windows.
fallback in the order of `merge.guitool`, `diff.tool`,
`merge.tool` until a tool is found.
---trust-exit-code::
---no-trust-exit-code::
+`--trust-exit-code`::
+`--no-trust-exit-code`::
Errors reported by the diff tool are ignored by default.
- Use `--trust-exit-code` to make 'git-difftool' exit when an
+ Use `--trust-exit-code` to make `git-difftool` exit when an
invoked diff tool returns a non-zero exit code.
+
-'git-difftool' will forward the exit code of the invoked tool when
+`git-difftool` will forward the exit code of the invoked tool when
`--trust-exit-code` is used.
See linkgit:git-diff[1] for the full list of supported options.
CONFIGURATION
-------------
-'git difftool' falls back to 'git mergetool' config variables when the
+`git difftool` falls back to `git mergetool` config variables when the
difftool equivalents have not been defined.
include::includes/cmd-config-section-rest.adoc[]
--
gitgitgadget
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 2/4] doc: convert git-range-diff manual page to synopsis style
2026-04-04 17:12 [PATCH 0/4] Doc difftool Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 1/4] doc: convert git-difftool manual page to synopsis style Jean-Noël Avila via GitGitGadget
@ 2026-04-04 17:12 ` Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 3/4] doc: convert git-shortlog " Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 4/4] doc: convert git-describe " Jean-Noël Avila via GitGitGadget
3 siblings, 0 replies; 5+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2026-04-04 17:12 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
* convert commands and options to synopsis style
* use _<placeholder>_ for arguments
* small style fixes
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-range-diff.adoc | 50 +++++++++++++++----------------
1 file changed, 25 insertions(+), 25 deletions(-)
diff --git a/Documentation/git-range-diff.adoc b/Documentation/git-range-diff.adoc
index b5e85d37f1..8805570845 100644
--- a/Documentation/git-range-diff.adoc
+++ b/Documentation/git-range-diff.adoc
@@ -7,8 +7,8 @@ git-range-diff - Compare two commit ranges (e.g. two versions of a branch)
SYNOPSIS
--------
-[verse]
-'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>]
+[synopsis]
+git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
[--no-dual-color] [--creation-factor=<factor>]
[--left-only | --right-only] [--diff-merges=<format>]
[--remerge-diff]
@@ -21,14 +21,14 @@ DESCRIPTION
This command shows the differences between two versions of a patch
series, or more generally, two commit ranges (ignoring merge commits).
-In the presence of `<path>` arguments, these commit ranges are limited
+In the presence of _<path>_ arguments, these commit ranges are limited
accordingly.
To that end, it first finds pairs of commits from both commit ranges
that correspond with each other. Two commits are said to correspond when
the diff between their patches (i.e. the author information, the commit
message and the commit diff) is reasonably small compared to the
-patches' size. See ``Algorithm`` below for details.
+patches' size. See 'Algorithm' below for details.
Finally, the list of matching commits is shown in the order of the
second commit range, with unmatched commits being inserted just after
@@ -37,7 +37,7 @@ all of their ancestors have been shown.
There are three ways to specify the commit ranges:
- `<range1> <range2>`: Either commit range can be of the form
- `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See `SPECIFYING RANGES`
+ `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See 'SPECIFYING RANGES'
in linkgit:gitrevisions[7] for more details.
- `<rev1>...<rev2>`. This is equivalent to
@@ -48,7 +48,7 @@ There are three ways to specify the commit ranges:
OPTIONS
-------
---no-dual-color::
+`--no-dual-color`::
When the commit diffs differ, `git range-diff` recreates the
original diffs' coloring, and adds outer -/+ diff markers with
the *background* being red/green to make it easier to see e.g.
@@ -56,33 +56,33 @@ OPTIONS
+
Additionally, the commit diff lines that are only present in the first commit
range are shown "dimmed" (this can be overridden using the `color.diff.<slot>`
-config setting where `<slot>` is one of `contextDimmed`, `oldDimmed` and
+config setting where _<slot>_ is one of `contextDimmed`, `oldDimmed` and
`newDimmed`), and the commit diff lines that are only present in the second
commit range are shown in bold (which can be overridden using the config
-settings `color.diff.<slot>` with `<slot>` being one of `contextBold`,
+settings `color.diff.<slot>` with _<slot>_ being one of `contextBold`,
`oldBold` or `newBold`).
+
This is known to `range-diff` as "dual coloring". Use `--no-dual-color`
to revert to color all lines according to the outer diff markers
(and completely ignore the inner diff when it comes to color).
---creation-factor=<percent>::
- Set the creation/deletion cost fudge factor to `<percent>`.
+`--creation-factor=<percent>`::
+ Set the creation/deletion cost fudge factor to _<percent>_.
Defaults to 60. Try a larger value if `git range-diff` erroneously
considers a large change a total rewrite (deletion of one commit
and addition of another), and a smaller one in the reverse case.
- See the ``Algorithm`` section below for an explanation of why this is
+ See the 'Algorithm' section below for an explanation of why this is
needed.
---left-only::
+`--left-only`::
Suppress commits that are missing from the first specified range
- (or the "left range" when using the `<rev1>...<rev2>` format).
+ (or the "left range" when using the `<rev1>...<rev2>` form).
---right-only::
+`--right-only`::
Suppress commits that are missing from the second specified range
- (or the "right range" when using the `<rev1>...<rev2>` format).
+ (or the "right range" when using the `<rev1>...<rev2>` form).
---diff-merges=<format>::
+`--diff-merges=<format>`::
Instead of ignoring merge commits, generate diffs for them using the
corresponding `--diff-merges=<format>` option of linkgit:git-log[1],
and include them in the comparison.
@@ -93,30 +93,30 @@ have produced. In other words, if a merge commit is the result of a
non-conflicting `git merge`, the `remerge` mode will represent it with an empty
diff.
---remerge-diff::
+`--remerge-diff`::
Convenience option, equivalent to `--diff-merges=remerge`.
---notes[=<ref>]::
---no-notes::
+`--notes[=<ref>]`::
+`--no-notes`::
This flag is passed to the `git log` program
(see linkgit:git-log[1]) that generates the patches.
-<range1> <range2>::
+`<range1> <range2>`::
Compare the commits specified by the two ranges, where
- `<range1>` is considered an older version of `<range2>`.
+ _<range1>_ is considered an older version of _<range2>_.
-<rev1>...<rev2>::
+`<rev1>...<rev2>`::
Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.
-<base> <rev1> <rev2>::
+`<base> <rev1> <rev2>`::
Equivalent to passing `<base>..<rev1>` and `<base>..<rev2>`.
- Note that `<base>` does not need to be the exact branch point
+ Note that _<base>_ does not need to be the exact branch point
of the branches. Example: after rebasing a branch `my-topic`,
`git range-diff my-topic@{u} my-topic@{1} my-topic` would
show the differences introduced by the rebase.
`git range-diff` also accepts the regular diff options (see
-linkgit:git-diff[1]), most notably the `--color=[<when>]` and
+linkgit:git-diff[1]), most notably the `--color[=<when>]` and
`--no-color` options. These options are used when generating the "diff
between patches", i.e. to compare the author, commit message and diff of
corresponding old/new commits. There is currently no means to tweak most of the
--
gitgitgadget
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 3/4] doc: convert git-shortlog manual page to synopsis style
2026-04-04 17:12 [PATCH 0/4] Doc difftool Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 1/4] doc: convert git-difftool manual page to synopsis style Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 2/4] doc: convert git-range-diff " Jean-Noël Avila via GitGitGadget
@ 2026-04-04 17:12 ` Jean-Noël Avila via GitGitGadget
2026-04-04 17:12 ` [PATCH 4/4] doc: convert git-describe " Jean-Noël Avila via GitGitGadget
3 siblings, 0 replies; 5+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2026-04-04 17:12 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
* convert commands and options to synopsis style
* use _<placeholder>_ for arguments
* small style fixes
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-shortlog.adoc | 60 ++++++++++++++++-----------------
1 file changed, 30 insertions(+), 30 deletions(-)
diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index a11b57c1cd..e067d39b38 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -3,63 +3,63 @@ git-shortlog(1)
NAME
----
-git-shortlog - Summarize 'git log' output
+git-shortlog - Summarize `git log` output
SYNOPSIS
--------
-[verse]
-'git shortlog' [<options>] [<revision-range>] [[--] <path>...]
-git log --pretty=short | 'git shortlog' [<options>]
+[synopsis]
+git shortlog [<options>] [<revision-range>] [[--] <path>...]
+git log --pretty=short | git shortlog [<options>]
DESCRIPTION
-----------
-Summarizes 'git log' output in a format suitable for inclusion
+Summarizes `git log` output in a format suitable for inclusion
in release announcements. Each commit will be grouped by author and title.
Additionally, "[PATCH]" will be stripped from the commit description.
If no revisions are passed on the command line and either standard input
-is not a terminal or there is no current branch, 'git shortlog' will
+is not a terminal or there is no current branch, `git shortlog` will
output a summary of the log read from standard input, without
reference to the current repository.
OPTIONS
-------
--n::
---numbered::
+`-n`::
+`--numbered`::
Sort output according to the number of commits per author instead
of author alphabetic order.
--s::
---summary::
+`-s`::
+`--summary`::
Suppress commit description and provide a commit count summary only.
--e::
---email::
+`-e`::
+`--email`::
Show the email address of each author.
---format[=<format>]::
+`--format[=<format>]`::
Instead of the commit subject, use some other information to
- describe each commit. '<format>' can be any string accepted
- by the `--format` option of 'git log', such as '* [%h] %s'.
- (See the "PRETTY FORMATS" section of linkgit:git-log[1].)
+ describe each commit. _<format>_ can be any string accepted
+ by the `--format` option of `git log`, such as '* [%h] %s'.
+ (See the 'PRETTY FORMATS' section of linkgit:git-log[1].)
+
Each pretty-printed commit will be rewrapped before it is shown.
---date=<format>::
+`--date=<format>`::
Show dates formatted according to the given date string. (See
- the `--date` option in the "Commit Formatting" section of
+ the `--date` option in the 'Commit Formatting' section of
linkgit:git-log[1]). Useful with `--group=format:<format>`.
---group=<type>::
- Group commits based on `<type>`. If no `--group` option is
- specified, the default is `author`. `<type>` is one of:
+`--group=<type>`::
+ Group commits based on _<type>_. If no `--group` option is
+ specified, the default is `author`. _<type>_ is one of:
+
--
- `author`, commits are grouped by author
- `committer`, commits are grouped by committer (the same as `-c`)
- - `trailer:<field>`, the `<field>` is interpreted as a case-insensitive
+ - `trailer:<field>`, the _<field>_ is interpreted as a case-insensitive
commit message trailer (see linkgit:git-interpret-trailers[1]). For
example, if your project uses `Reviewed-by` trailers, you might want
to see who has been reviewing with
@@ -76,7 +76,7 @@ unless the `--email` option is specified. If the value cannot be parsed
as an identity, it will be taken literally and completely.
- `format:<format>`, any string accepted by the `--format` option of
- 'git log'. (See the "PRETTY FORMATS" section of
+ `git log`. (See the 'PRETTY FORMATS' section of
linkgit:git-log[1].)
--
+
@@ -85,11 +85,11 @@ value (but again, only once per unique value in that commit). For
example, `git shortlog --group=author --group=trailer:co-authored-by`
counts both authors and co-authors.
--c::
---committer::
+`-c`::
+`--committer`::
This is an alias for `--group=committer`.
--w[<width>[,<indent1>[,<indent2>]]]::
+`-w[<width>[,<indent1>[,<indent2>]]]`::
Linewrap the output by wrapping each line at `width`. The first
line of each entry is indented by `indent1` spaces, and the second
and subsequent lines are indented by `indent2` spaces. `width`,
@@ -98,16 +98,16 @@ counts both authors and co-authors.
If width is `0` (zero) then indent the lines of the output without wrapping
them.
-<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>...`::
Consider only commits that are enough to explain how the files
that match the specified paths came to be.
+
--
gitgitgadget
^ permalink raw reply related [flat|nested] 5+ messages in thread* [PATCH 4/4] doc: convert git-describe manual page to synopsis style
2026-04-04 17:12 [PATCH 0/4] Doc difftool Jean-Noël Avila via GitGitGadget
` (2 preceding siblings ...)
2026-04-04 17:12 ` [PATCH 3/4] doc: convert git-shortlog " Jean-Noël Avila via GitGitGadget
@ 2026-04-04 17:12 ` Jean-Noël Avila via GitGitGadget
3 siblings, 0 replies; 5+ messages in thread
From: Jean-Noël Avila via GitGitGadget @ 2026-04-04 17:12 UTC (permalink / raw)
To: git; +Cc: Jean-Noël Avila, Jean-Noël Avila
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
* convert commands and options to synopsis style
* use _<placeholder>_ for arguments
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
Documentation/git-describe.adoc | 96 ++++++++++++++++-----------------
1 file changed, 48 insertions(+), 48 deletions(-)
diff --git a/Documentation/git-describe.adoc b/Documentation/git-describe.adoc
index 08ff715709..b2cb1e47e4 100644
--- a/Documentation/git-describe.adoc
+++ b/Documentation/git-describe.adoc
@@ -7,10 +7,10 @@ git-describe - Give an object a human readable name based on an available ref
SYNOPSIS
--------
-[verse]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
-'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
-'git describe' <blob>
+[synopsis]
+git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
+git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
+git describe <blob>
DESCRIPTION
-----------
@@ -22,70 +22,70 @@ abbreviated object name of the most recent commit. The result
is a "human-readable" object name which can also be used to
identify the commit to other git commands.
-By default (without --all or --tags) `git describe` only shows
+By default (without `--all` or `--tags`) `git describe` only shows
annotated tags. For more information about creating annotated tags
-see the -a and -s options to linkgit:git-tag[1].
+see the `-a` and `-s` options to linkgit:git-tag[1].
If the given object refers to a blob, it will be described
as `<commit-ish>:<path>`, such that the blob can be found
-at `<path>` in the `<commit-ish>`, which itself describes the
+at _<path>_ in the _<commit-ish>_, which itself describes the
first commit in which this blob occurs in a reverse revision walk
-from HEAD.
+from `HEAD`.
OPTIONS
-------
-<commit-ish>...::
- Commit-ish object names to describe. Defaults to HEAD if omitted.
+`<commit-ish>...`::
+ Commit-ish object names to describe. Defaults to `HEAD` if omitted.
---dirty[=<mark>]::
---broken[=<mark>]::
+`--dirty[=<mark>]`::
+`--broken[=<mark>]`::
Describe the state of the working tree. When the working
- tree matches HEAD, the output is the same as "git describe
- HEAD". If the working tree has local modification "-dirty"
+ tree matches `HEAD`, the output is the same as `git describe HEAD`.
+ If the working tree has local modification, `-dirty`
is appended to it. If a repository is corrupt and Git
cannot determine if there is local modification, Git will
- error out, unless `--broken' is given, which appends
- the suffix "-broken" instead.
+ error out, unless `--broken` is given, which appends
+ the suffix `-broken` instead.
---all::
+`--all`::
Instead of using only the annotated tags, use any ref
found in `refs/` namespace. This option enables matching
any known branch, remote-tracking branch, or lightweight tag.
---tags::
+`--tags`::
Instead of using only the annotated tags, use any tag
found in `refs/tags` namespace. This option enables matching
a lightweight (non-annotated) tag.
---contains::
+`--contains`::
Instead of finding the tag that predates the commit, find
the tag that comes after the commit, and thus contains it.
- Automatically implies --tags.
+ Automatically implies `--tags`.
---abbrev=<n>::
+`--abbrev=<n>`::
Instead of using the default number of hexadecimal digits (which
will vary according to the number of objects in the repository with
- a default of 7) of the abbreviated object name, use <n> digits, or
- as many digits as needed to form a unique object name. An <n> of 0
+ a default of 7) of the abbreviated object name, use _<n>_ digits, or
+ as many digits as needed to form a unique object name. An _<n>_ of 0
will suppress long format, only showing the closest tag.
---candidates=<n>::
+`--candidates=<n>`::
Instead of considering only the 10 most recent tags as
candidates to describe the input commit-ish consider
- up to <n> candidates. Increasing <n> above 10 will take
+ up to _<n>_ candidates. Increasing _<n>_ above 10 will take
slightly longer but may produce a more accurate result.
- An <n> of 0 will cause only exact matches to be output.
+ An _<n>_ of 0 will cause only exact matches to be output.
---exact-match::
+`--exact-match`::
Only output exact matches (a tag directly references the
- supplied commit). This is a synonym for --candidates=0.
+ supplied commit). This is a synonym for `--candidates=0`.
---debug::
+`--debug`::
Verbosely display information about the searching strategy
being employed to standard error. The tag name will still
be printed to standard out.
---long::
+`--long`::
Always output the long format (the tag, the number of commits
and the abbreviated commit name) even when it matches a tag.
This is useful when you want to see parts of the commit object name
@@ -94,8 +94,8 @@ OPTIONS
describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
that points at object deadbee....).
---match <pattern>::
- Only consider tags matching the given `glob(7)` pattern,
+`--match <pattern>`::
+ Only consider tags matching the given `glob`(7) pattern,
excluding the "refs/tags/" prefix. If used with `--all`, it also
considers local branches and remote-tracking references matching the
pattern, excluding respectively "refs/heads/" and "refs/remotes/"
@@ -104,22 +104,22 @@ OPTIONS
matching any of the patterns will be considered. Use `--no-match` to
clear and reset the list of patterns.
---exclude <pattern>::
- Do not consider tags matching the given `glob(7)` pattern, excluding
+`--exclude <pattern>`::
+ Do not consider tags matching the given `glob`(7) pattern, excluding
the "refs/tags/" prefix. If used with `--all`, it also does not consider
local branches and remote-tracking references matching the pattern,
- excluding respectively "refs/heads/" and "refs/remotes/" prefix;
+ excluding respectively "`refs/heads/`" and "`refs/remotes/`" prefix;
references of other types are never considered. If given multiple times,
a list of patterns will be accumulated and tags matching any of the
- patterns will be excluded. When combined with --match a tag will be
- considered when it matches at least one --match pattern and does not
- match any of the --exclude patterns. Use `--no-exclude` to clear and
+ patterns will be excluded. When combined with `--match` a tag will be
+ considered when it matches at least one `--match` pattern and does not
+ match any of the `--exclude` patterns. Use `--no-exclude` to clear and
reset the list of patterns.
---always::
+`--always`::
Show uniquely abbreviated commit object as fallback.
---first-parent::
+`--first-parent`::
Follow only the first parent commit upon seeing a merge commit.
This is useful when you wish to not match tags on branches merged
in the history of the target commit.
@@ -139,8 +139,8 @@ an abbreviated object name for the commit itself ("2414721")
at the end.
The number of additional commits is the number
-of commits which would be displayed by "git log v1.0.4..parent".
-The hash suffix is "-g" + an unambiguous abbreviation for the tip commit
+of commits which would be displayed by `git log v1.0.4..parent`.
+The hash suffix is "`-g`" + an unambiguous abbreviation for the tip commit
of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The
length of the abbreviation scales as the repository grows, using the
approximate number of objects in the repository and a bit of math
@@ -149,12 +149,12 @@ The "g" prefix stands for "git" and is used to allow describing the version of
a software depending on the SCM the software is managed with. This is useful
in an environment where people may use different SCMs.
-Doing a 'git describe' on a tag-name will just show the tag name:
+Doing a `git describe` on a tag-name will just show the tag name:
[torvalds@g5 git]$ git describe v1.0.4
v1.0.4
-With --all, the command can use branch heads as references, so
+With `--all`, the command can use branch heads as references, so
the output shows the reference path as well:
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
@@ -163,7 +163,7 @@ the output shows the reference path as well:
[torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b
-With --abbrev set to 0, the command can be used to find the
+With `--abbrev` set to 0, the command can be used to find the
closest tagname without any suffix:
[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
@@ -179,13 +179,13 @@ be sufficient to disambiguate these commits.
SEARCH STRATEGY
---------------
-For each commit-ish supplied, 'git describe' will first look for
+For each commit-ish supplied, `git describe` will first look for
a tag which tags exactly that commit. Annotated tags will always
be preferred over lightweight tags, and tags with newer dates will
always be preferred over tags with older dates. If an exact match
is found, its name will be output and searching will stop.
-If an exact match was not found, 'git describe' will walk back
+If an exact match was not found, `git describe` will walk back
through the commit history to locate an ancestor commit which
has been tagged. The ancestor's tag will be output along with an
abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
@@ -203,7 +203,7 @@ BUGS
Tree objects as well as tag objects not pointing at commits, cannot be described.
When describing blobs, the lightweight tags pointing at blobs are ignored,
-but the blob is still described as <commit-ish>:<path> despite the lightweight
+but the blob is still described as `<commit-ish>:<path>` despite the lightweight
tag being favorable.
GIT
--
gitgitgadget
^ permalink raw reply related [flat|nested] 5+ messages in thread