for-each-ref: clean up documentation of --format
Move the description of the `*` prefix from the --format option documentation to the part of the command documentation that deals with other object type-specific modifiers. Also reorganize and reword the remaining --format documentation so that the explanation of the default format doesn't interrupt the details on format string interpolation. Signed-off-by: Victoria Dye <vdye@github.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Victoria Dye committed
Nov 14, 2023 at 19:53 UTC
d1dfe6e936777c2f64d19fe516cff83e1ef9dca6
1 file changed
+12
-11
Documentation/git-for-each-ref.txt
+12
-11
@@ -51,17 +51,14 @@ OPTIONS
51
key.
52
53
--format=<format>::
54
- A string that interpolates `%(fieldname)` from a ref being shown
55
- and the object it points at. If `fieldname`
56
- is prefixed with an asterisk (`*`) and the ref points
57
- at a tag object, use the value for the field in the object
58
- which the tag object refers to (instead of the field in the tag object).
59
- When unspecified, `<format>` defaults to
60
- `%(objectname) SPC %(objecttype) TAB %(refname)`.
61
- It also interpolates `%%` to `%`, and `%xx` where `xx`
62
- are hex digits interpolates to character with hex code
63
- `xx`; for example `%00` interpolates to `\0` (NUL),
64
- `%09` to `\t` (TAB) and `%0a` to `\n` (LF).
54
+ A string that interpolates `%(fieldname)` from a ref being shown and
55
+ the object it points at. In addition, the string literal `%%`
56
+ renders as `%` and `%xx` - where `xx` are hex digits - renders as
57
+ the character with hex code `xx`. For example, `%00` interpolates to
58
+ `\0` (NUL), `%09` to `\t` (TAB), and `%0a` to `\n` (LF).
59
++
60
+When unspecified, `<format>` defaults to `%(objectname) SPC %(objecttype)
61
+TAB %(refname)`.
62
63
--color[=<when>]::
64
Respect any colors specified in the `--format` option. The
@@ -298,6 +295,10 @@ fields will correspond to the appropriate date or name-email-date tuple
295
from the `committer` or `tagger` fields depending on the object type.
296
These are intended for working on a mix of annotated and lightweight tags.
297
298
+For tag objects, a `fieldname` prefixed with an asterisk (`*`) expands to
299
+the `fieldname` value of object the tag points at, rather than that of the
300
+tag object itself.
301
+
302
Fields that have name-email-date tuple as its value (`author`,
303
`committer`, and `tagger`) can be suffixed with `name`, `email`,
304
and `date` to extract the named component. For email fields (`authoremail`,