admin/git
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc:git-for-each-ref: fix styling and typos

Browse Source 
This commit fixes the synopsis syntax and changes the wording of a few
descriptions to be more consistent with the rest of the documentation.

It is a prepartion for the next commit that checks that synopsis style is
applied consistently across a manual page.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Jean-Noël Avila
2025-08-11 20:53:19 +00:00
committed by Junio C Hamano
parent 03a353bb97
commit 93203872d7
1 changed files with 131 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

262
Documentation/git-for-each-ref.adoc
View File

@@ -14,101 +14,98 @@ git for-each-ref [--count=<count>] [--shell|--perl|--python|--tcl]
[--merged[=<object>]] [--no-merged[=<object>]] [--merged[=<object>]] [--no-merged[=<object>]]
[--contains[=<object>]] [--no-contains[=<object>]] [--contains[=<object>]] [--no-contains[=<object>]]
[(--exclude=<pattern>)...] [--start-after=<marker>] [(--exclude=<pattern>)...] [--start-after=<marker>]
[ --stdin | <pattern>... ] [ --stdin | (<pattern>...)]
DESCRIPTION DESCRIPTION
----------- -----------
Iterate over all refs that match `<pattern>` and show them Iterate over all refs that match _<pattern>_ and show them
according to the given `<format>`, after sorting them according according to the given _<format>_, after sorting them according
to the given set of `<key>`. If `<count>` is given, stop after to the given set of _<key>_. If _<count>_ is given, stop after
showing that many refs. The interpolated values in `<format>` showing that many refs. The interpolated values in _<format>_
can optionally be quoted as string literals in the specified can optionally be quoted as string literals in the specified
host language allowing their direct evaluation in that language. host language allowing their direct evaluation in that language.
OPTIONS OPTIONS
------- -------
<pattern>...:: `<pattern>...`::
If one or more patterns are given, only refs are shown that If one or more _<pattern>_ parameters are given, only refs are shown that
match against at least one pattern, either using fnmatch(3) or match against at least one pattern, either using `fnmatch`(3) or
literally, in the latter case matching completely or from the literally, in the latter case matching completely or from the
beginning up to a slash. beginning up to a slash.
--stdin:: `--stdin`::
If `--stdin` is supplied, then the list of patterns is read from The list of patterns is read from standard input instead of from
standard input instead of from the argument list. the argument list.
--count=<count>:: `--count=<count>`::
By default the command shows all refs that match Stop after showing _<count>_ refs.
`<pattern>`. This option makes it stop after showing
that many refs.
--sort=<key>:: `--sort=<key>`::
A field name to sort on. Prefix `-` to sort in Sort on the field name _<key>_. Prefix `-` to sort in
descending order of the value. When unspecified, descending order of the value. When unspecified,
`refname` is used. You may use the --sort=<key> option `refname` is used. You may use the `--sort=<key>` option
multiple times, in which case the last key becomes the primary multiple times, in which case the last key becomes the primary
key. key.
--format=<format>:: `--format[=<format>]`::
A string that interpolates `%(fieldname)` from a ref being shown and A string that interpolates `%(fieldname)` from a ref being shown and
the object it points at. In addition, the string literal `%%` the object it points at. In addition, the string literal `%%`
renders as `%` and `%xx` - where `xx` are hex digits - renders as renders as `%` and `%xx` - where `xx` are hex digits - renders as
the character with hex code `xx`. For example, `%00` interpolates to the character with hex code `xx`. For example, `%00` interpolates to
`\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF). `\0` (_NUL_), `%09` to `\t` (_TAB_), and `%0a` to `\n` (_LF_).
+
When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype) When unspecified, _<format>_ defaults to `%(objectname) SPC %(objecttype)
TAB %(refname)`. TAB %(refname)`.
--color[=<when>]:: `--color[=<when>]`::
Respect any colors specified in the `--format` option. The Respect any colors specified in the `--format` option. The
`<when>` field must be one of `always`, `never`, or `auto` (if _<when__ field must be one of `always`, `never`, or `auto` (if
`<when>` is absent, behave as if `always` was given). `<when>` is absent, behave as if `always` was given).
--shell:: `--shell`::
--perl:: `--perl`::
--python:: `--python`::
--tcl:: `--tcl`::
If given, strings that substitute `%(fieldname)` If given, strings that substitute `%(fieldname)`
placeholders are quoted as string literals suitable for placeholders are quoted as string literals suitable for
the specified host language. This is meant to produce the specified host language. This is meant to produce
a scriptlet that can directly be `eval`ed. a scriptlet that can directly be "eval"ed.
--points-at=<object>:: `--points-at=<object>`::
Only list refs which points at the given object. Only list refs which points at the given object.
--merged[=<object>]:: `--merged[=<object>]`::
Only list refs whose tips are reachable from the Only list refs whose tips are reachable from the
specified commit (HEAD if not specified). specified commit (`HEAD` if not specified).
--no-merged[=<object>]:: `--no-merged[=<object>]`::
Only list refs whose tips are not reachable from the Only list refs whose tips are not reachable from _<object>_(`HEAD` if not
specified commit (HEAD if not specified).
--contains[=<object>]::
Only list refs which contain the specified commit (HEAD if not
specified). specified).
--no-contains[=<object>]:: `--contains[=<object>]`::
Only list refs which don't contain the specified commit (HEAD Only list refs which contain _<object>_(`HEAD` if not specified).
`--no-contains[=<object>]`::
Only list refs which don't contain _<object>_ (`HEAD`
if not specified). if not specified).
--ignore-case:: `--ignore-case`::
Sorting and filtering refs are case insensitive. Sorting and filtering refs are case insensitive.
--omit-empty:: `--omit-empty`::
Do not print a newline after formatted refs where the format expands Do not print a newline after formatted refs where the format expands
to the empty string. to the empty string.
--exclude=<pattern>:: `--exclude=<excluded-pattern>`::
If one or more patterns are given, only refs which do not match If one or more `--exclude` options are given, only refs which do not
any excluded pattern(s) are shown. Matching is done using the match any _<excluded-pattern>_ parameters are shown. Matching is done
same rules as `<pattern>` above. using the same rules as _<pattern>_ above.
--include-root-refs:: `--include-root-refs`::
List root refs (HEAD and pseudorefs) apart from regular refs. List root refs (`HEAD` and pseudorefs) apart from regular refs.
--start-after=<marker>:: `--start-after=<marker>`::
Allows paginating the output by skipping references up to and including the Allows paginating the output by skipping references up to and including the
specified marker. When paging, it should be noted that references may be specified marker. When paging, it should be noted that references may be
deleted, modified or added between invocations. Output will only yield those deleted, modified or added between invocations. Output will only yield those
@@ -126,44 +123,44 @@ keys.
For all objects, the following names can be used: For all objects, the following names can be used:
refname:: `refname`::
The name of the ref (the part after $GIT_DIR/). The name of the ref (the part after `$GIT_DIR/`).
For a non-ambiguous short name of the ref append `:short`. For a non-ambiguous short name of the ref append `:short`.
The option core.warnAmbiguousRefs is used to select the strict The option `core.warnAmbiguousRefs` is used to select the strict
abbreviation mode. If `lstrip=<N>` (`rstrip=<N>`) is appended, strips `<N>` abbreviation mode. If `lstrip=<n>` (`rstrip=<n>`) is appended, strip _<n>_
slash-separated path components from the front (back) of the refname slash-separated path components from the front (back) of the refname
(e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and (e.g. `%(refname:lstrip=2)` turns `refs/tags/foo` into `foo` and
`%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`). `%(refname:rstrip=2)` turns `refs/tags/foo` into `refs`).
If `<N>` is a negative number, strip as many path components as If _<n>_ is a negative number, strip as many path components as
necessary from the specified end to leave `-<N>` path components necessary from the specified end to leave `-<n>` path components
(e.g. `%(refname:lstrip=-2)` turns (e.g. `%(refname:lstrip=-2)` turns
`refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)` `refs/tags/foo` into `tags/foo` and `%(refname:rstrip=-1)`
turns `refs/tags/foo` into `refs`). When the ref does not have turns `refs/tags/foo` into `refs`). When the ref does not have
enough components, the result becomes an empty string if enough components, the result becomes an empty string if
stripping with positive <N>, or it becomes the full refname if stripping with positive _<n>_, or it becomes the full refname if
stripping with negative <N>. Neither is an error. stripping with negative _<N>_. Neither is an error.
+ +
`strip` can be used as a synonym to `lstrip`. `strip` can be used as a synonym to `lstrip`.
objecttype:: `objecttype`::
The type of the object (`blob`, `tree`, `commit`, `tag`). The type of the object (`blob`, `tree`, `commit`, `tag`).
objectsize:: `objectsize`::
The size of the object (the same as 'git cat-file -s' reports). The size of the object (the same as 'git cat-file -s' reports).
Append `:disk` to get the size, in bytes, that the object takes up on Append `:disk` to get the size, in bytes, that the object takes up on
disk. See the note about on-disk sizes in the `CAVEATS` section below. disk. See the note about on-disk sizes in the 'CAVEATS' section below.
objectname:: `objectname`::
The object name (aka SHA-1). The object name (aka SHA-1).
For a non-ambiguous abbreviation of the object name append `:short`. For a non-ambiguous abbreviation of the object name append `:short`.
For an abbreviation of the object name with desired length append For an abbreviation of the object name with desired length append
`:short=<length>`, where the minimum length is MINIMUM_ABBREV. The `:short=<length>`, where the minimum length is `MINIMUM_ABBREV`. The
length may be exceeded to ensure unique object names. length may be exceeded to ensure unique object names.
deltabase:: `deltabase`::
This expands to the object name of the delta base for the This expands to the object name of the delta base for the
given object, if it is stored as a delta. Otherwise it given object, if it is stored as a delta. Otherwise it
expands to the null object name (all zeroes). expands to the null object name (all zeroes).
upstream:: `upstream`::
The name of a local ref which can be considered ``upstream'' The name of a local ref which can be considered ``upstream''
from the displayed ref. Respects `:short`, `:lstrip` and from the displayed ref. Respects `:short`, `:lstrip` and
`:rstrip` in the same way as `refname` above. Additionally `:rstrip` in the same way as `refname` above. Additionally
@@ -185,100 +182,103 @@ Has no effect if the ref does not have tracking information associated
with it. All the options apart from `nobracket` are mutually exclusive, with it. All the options apart from `nobracket` are mutually exclusive,
but if used together the last option is selected. but if used together the last option is selected.
push:: `push`::
The name of a local ref which represents the `@{push}` The name of a local ref which represents the `@{push}`
location for the displayed ref. Respects `:short`, `:lstrip`, location for the displayed ref. Respects `:short`, `:lstrip`,
`:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref` `:rstrip`, `:track`, `:trackshort`, `:remotename`, and `:remoteref`
options as `upstream` does. Produces an empty string if no `@{push}` options as `upstream` does. Produces an empty string if no `@{push}`
ref is configured. ref is configured.
HEAD:: `HEAD`::
'*' if HEAD matches current ref (the checked out branch), ' ' `*` if `HEAD` matches current ref (the checked out branch), ' '
otherwise. otherwise.
color:: `color`::
Change output color. Followed by `:<colorname>`, where color Change output color. Followed by `:<colorname>`, where color
names are described under Values in the "CONFIGURATION FILE" names are described under Values in the "CONFIGURATION FILE"
section of linkgit:git-config[1]. For example, section of linkgit:git-config[1]. For example,
`%(color:bold red)`. `%(color:bold red)`.
align:: `align`::
Left-, middle-, or right-align the content between Left-, middle-, or right-align the content between
%(align:...) and %(end). The "align:" is followed by `%(align:...)` and `%(end)`. The "`align:`" is followed by
`width=<width>` and `position=<position>` in any order `width=<width>` and `position=<position>` in any order
separated by a comma, where the `<position>` is either left, separated by a comma, where the _<position>_ is either `left`,
right or middle, default being left and `<width>` is the total `right` or `middle`, default being `left` and _<width>_ is the total
length of the content with alignment. For brevity, the length of the content with alignment. For brevity, the
"width=" and/or "position=" prefixes may be omitted, and bare "width=" and/or "position=" prefixes may be omitted, and bare
<width> and <position> used instead. For instance, _<width>_ and _<position>_ used instead. For instance,
`%(align:<width>,<position>)`. If the contents length is more `%(align:<width>,<position>)`. If the contents length is more
than the width then no alignment is performed. If used with than the width then no alignment is performed. If used with
`--quote` everything in between %(align:...) and %(end) is `--quote` everything in between `%(align:...)` and `%(end)` is
quoted, but if nested then only the topmost level performs quoted, but if nested then only the topmost level performs
quoting. quoting.
if:: `if`::
Used as %(if)...%(then)...%(end) or Used as `%(if)...%(then)...%(end)` or
%(if)...%(then)...%(else)...%(end). If there is an atom with `%(if)...%(then)...%(else)...%(end)`. If there is an atom with
value or string literal after the %(if) then everything after value or string literal after the `%(if)` then everything after
the %(then) is printed, else if the %(else) atom is used, then the `%(then)` is printed, else if the `%(else)` atom is used, then
everything after %(else) is printed. We ignore space when everything after %(else) is printed. We ignore space when
evaluating the string before %(then), this is useful when we evaluating the string before `%(then)`, this is useful when we
use the %(HEAD) atom which prints either "*" or " " and we use the `%(HEAD)` atom which prints either "`*`" or " " and we
want to apply the 'if' condition only on the 'HEAD' ref. want to apply the 'if' condition only on the `HEAD` ref.
Append ":equals=<string>" or ":notequals=<string>" to compare Append "`:equals=<string>`" or "`:notequals=<string>`" to compare
the value between the %(if:...) and %(then) atoms with the the value between the `%(if:...)` and `%(then)` atoms with the
given string. given string.
symref:: `symref`::
The ref which the given symbolic ref refers to. If not a The ref which the given symbolic ref refers to. If not a
symbolic ref, nothing is printed. Respects the `:short`, symbolic ref, nothing is printed. Respects the `:short`,
`:lstrip` and `:rstrip` options in the same way as `refname` `:lstrip` and `:rstrip` options in the same way as `refname`
above. above.
signature:: `signature`::
The GPG signature of a commit. The GPG signature of a commit.
signature:grade:: `signature:grade`::
Show "G" for a good (valid) signature, "B" for a bad Show
signature, "U" for a good signature with unknown validity, "X" `G`;; for a good (valid) signature
for a good signature that has expired, "Y" for a good `B`;; for a bad signature
signature made by an expired key, "R" for a good signature `U`;; for a good signature with unknown validity
made by a revoked key, "E" if the signature cannot be `X`;; for a good signature that has expired
checked (e.g. missing key) and "N" for no signature. `Y`;; for a good signature made by an expired key
`R`;; for a good signature made by a revoked key
`E`;; if the signature cannot be checked (e.g. missing key)
`N`;; for no signature.
signature:signer:: `signature:signer`::
The signer of the GPG signature of a commit. The signer of the GPG signature of a commit.
signature:key:: `signature:key`::
The key of the GPG signature of a commit. The key of the GPG signature of a commit.
signature:fingerprint:: `signature:fingerprint`::
The fingerprint of the GPG signature of a commit. The fingerprint of the GPG signature of a commit.
signature:primarykeyfingerprint:: `signature:primarykeyfingerprint`::
The primary key fingerprint of the GPG signature of a commit. The primary key fingerprint of the GPG signature of a commit.
signature:trustlevel:: `signature:trustlevel`::
The trust level of the GPG signature of a commit. Possible The trust level of the GPG signature of a commit. Possible
outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`. outputs are `ultimate`, `fully`, `marginal`, `never` and `undefined`.
worktreepath:: `worktreepath`::
The absolute path to the worktree in which the ref is checked The absolute path to the worktree in which the ref is checked
out, if it is checked out in any linked worktree. Empty string out, if it is checked out in any linked worktree. Empty string
otherwise. otherwise.
ahead-behind:<committish>:: `ahead-behind:<commit-ish>`::
Two integers, separated by a space, demonstrating the number of Two integers, separated by a space, demonstrating the number of
commits ahead and behind, respectively, when comparing the output commits ahead and behind, respectively, when comparing the output
ref to the `<committish>` specified in the format. ref to the _<committish>_ specified in the format.
is-base:<committish>:: `is-base:<commit-ish>`::
In at most one row, `(<committish>)` will appear to indicate the ref In at most one row, `(<commit-ish>)` will appear to indicate the ref
that is most likely the ref used as a starting point for the branch that is most likely the ref used as a starting point for the branch
that produced `<committish>`. This choice is made using a heuristic: that produced _<commit-ish>_. This choice is made using a heuristic:
choose the ref that minimizes the number of commits in the choose the ref that minimizes the number of commits in the
first-parent history of `<committish>` and not in the first-parent first-parent history of _<commit-ish>_ and not in the first-parent
history of the ref. history of the ref.
+ +
For example, consider the following figure of first-parent histories of For example, consider the following figure of first-parent histories of
@@ -312,29 +312,29 @@ common first-parent ancestor of `B` and `C` and ties are broken by the
earliest ref in the sorted order. earliest ref in the sorted order.
+ +
Note that this token will not appear if the first-parent history of Note that this token will not appear if the first-parent history of
`<committish>` does not intersect the first-parent histories of the _<commit-ish>_ does not intersect the first-parent histories of the
filtered refs. filtered refs.
describe[:options]:: `describe[:<option>,...]`::
A human-readable name, like linkgit:git-describe[1]; A human-readable name, like linkgit:git-describe[1];
empty string for undescribable commits. The `describe` string may empty string for undescribable commits. The `describe` string may
be followed by a colon and one or more comma-separated options. be followed by a colon and one or more comma-separated options.
+ +
-- --
tags=<bool-value>;; `tags=<bool-value>`;;
Instead of only considering annotated tags, consider Instead of only considering annotated tags, consider
lightweight tags as well; see the corresponding option in lightweight tags as well; see the corresponding option in
linkgit:git-describe[1] for details. linkgit:git-describe[1] for details.
abbrev=<number>;; `abbrev=<number>`;;
Use at least <number> hexadecimal digits; see the corresponding Use at least _<number>_ hexadecimal digits; see the corresponding
option in linkgit:git-describe[1] for details. option in linkgit:git-describe[1] for details.
match=<pattern>;; `match=<pattern>`;;
Only consider tags matching the given `glob(7)` pattern, Only consider tags matching the `glob`(7) _<pattern>_,
excluding the "refs/tags/" prefix; see the corresponding option excluding the `refs/tags/` prefix; see the corresponding option
in linkgit:git-describe[1] for details. in linkgit:git-describe[1] for details.
exclude=<pattern>;; `exclude=<pattern>`;;
Do not consider tags matching the given `glob(7)` pattern, Do not consider tags matching the `glob`(7) _<pattern>_,
excluding the "refs/tags/" prefix; see the corresponding option excluding the `refs/tags/` prefix; see the corresponding option
in linkgit:git-describe[1] for details. in linkgit:git-describe[1] for details.
-- --
@@ -366,7 +366,7 @@ variable (see linkgit:gitmailmap[5]).
The raw data in an object is `raw`. The raw data in an object is `raw`.
raw:size:: `raw:size`::
The raw data size of the object. The raw data size of the object.
Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`, Note that `--format=%(raw)` can not be used with `--python`, `--shell`, `--tcl`,
@@ -376,10 +376,10 @@ variable type.
The message in a commit or a tag object is `contents`, from which The message in a commit or a tag object is `contents`, from which
`contents:<part>` can be used to extract various parts out of: `contents:<part>` can be used to extract various parts out of:
contents:size:: `contents:size`::
The size in bytes of the commit or tag message. The size in bytes of the commit or tag message.
contents:subject:: `contents:subject`::
The first paragraph of the message, which typically is a The first paragraph of the message, which typically is a
single line, is taken as the "subject" of the commit or the single line, is taken as the "subject" of the commit or the
tag message. tag message.
@@ -387,19 +387,19 @@ contents:subject::
obtain same results. `:sanitize` can be appended to `subject` for obtain same results. `:sanitize` can be appended to `subject` for
subject line suitable for filename. subject line suitable for filename.
contents:body:: `contents:body`::
The remainder of the commit or the tag message that follows The remainder of the commit or the tag message that follows
the "subject". the "subject".
contents:signature:: `contents:signature`::
The optional GPG signature of the tag. The optional GPG signature of the tag.
contents:lines=N:: `contents:lines=<n>`::
The first `N` lines of the message. The first _<n>_ lines of the message.
Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1] Additionally, the trailers as interpreted by linkgit:git-interpret-trailers[1]
are obtained as `trailers[:options]` (or by using the historical alias are obtained as `trailers[:<option>,...]` (or by using the historical alias
`contents:trailers[:options]`). For valid [:option] values see `trailers` `contents:trailers[:<option>,...]`). For valid _<option>_ values see `trailers`
section of linkgit:git-log[1]. section of linkgit:git-log[1].
For sorting purposes, fields with numeric values sort in numeric order For sorting purposes, fields with numeric values sort in numeric order
@@ -419,8 +419,8 @@ option to linkgit:git-rev-list[1] takes). If this formatting is provided in
a `--sort` key, references will be sorted according to the byte-value of the a `--sort` key, references will be sorted according to the byte-value of the
formatted string rather than the numeric value of the underlying timestamp. formatted string rather than the numeric value of the underlying timestamp.
Some atoms like %(align) and %(if) always require a matching %(end). Some atoms like `%(align)` and `%(if)` always require a matching `%(end)`.
We call them "opening atoms" and sometimes denote them as %($open). We call them "opening atoms" and sometimes denote them as `%($open)`.
When a scripting language specific quoting is in effect, everything When a scripting language specific quoting is in effect, everything
between a top-level opening atom and its matching %(end) is evaluated between a top-level opening atom and its matching %(end) is evaluated
@@ -438,7 +438,7 @@ An example directly producing formatted text. Show the most recent
#!/bin/sh #!/bin/sh
git for-each-ref --count=3 --sort='-*authordate' \ git for-each-ref --count=3 --sort='-*authordate' \
--format='From: %(*authorname) %(*authoremail) `--format='From: %(*authorname) %(*authoremail)
Subject: %(*subject) Subject: %(*subject)
Date: %(*authordate) Date: %(*authordate)
Ref: %(*refname) Ref: %(*refname)
@@ -449,7 +449,7 @@ Ref: %(*refname)
A simple example showing the use of shell eval on the output, A simple example showing the use of shell eval on the output,
demonstrating the use of --shell. List the prefixes of all heads: demonstrating the use of `--shell`. List the prefixes of all heads:
------------ ------------
#!/bin/sh #!/bin/sh
@@ -517,7 +517,7 @@ eval "$eval"
------------ ------------
An example to show the usage of %(if)...%(then)...%(else)...%(end). An example to show the usage of `%(if)...%(then)...%(else)...%(end)`.
This prefixes the current branch with a star. This prefixes the current branch with a star.
------------ ------------
@@ -525,7 +525,7 @@ git for-each-ref --format="%(if)%(HEAD)%(then)* %(else) %(end)%(refname:short)"
------------ ------------
An example to show the usage of %(if)...%(then)...%(end). An example to show the usage of `%(if)...%(then)...%(end)`.
This prints the authorname, if present. This prints the authorname, if present.
------------ ------------