Documentation: use proper wording for ref format strings
Various commands list refs and allow to use a format string for the output that interpolates from the ref as well as the object it points at (for-each-ref; branch and tag in list mode). Currently, the documentation talks about interpolating from the object. This is confusing because a ref points to an object but not vice versa, so the object cannot possible know %(refname), for example. Thus, this is wrong independent of refs being objects (one day, maybe) or not. Change the wording to make this clearer (and distinguish it from formats for the log family). Signed-off-by: Michael J Gruber <git@grubix.eu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael J Gruber committed
Aug 18, 2017 at 16:51 UTC
e4933cee53bce14ae040d02d0febd678c5686dde
3 files changed
+6
-6
Documentation/git-branch.txt
+2
-2
@@ -267,8 +267,8 @@ start-point is either a local or remote-tracking branch.
267
Only list branches of the given object.
268
269
--format <format>::
270
- A string that interpolates `%(fieldname)` from the object
271
- pointed at by a ref being shown. The format is the same as
270
+ A string that interpolates `%(fieldname)` from a branch ref being shown
271
+ and the object it points at. The format is the same as
272
that of linkgit:git-for-each-ref[1].
273
274
Examples
Documentation/git-for-each-ref.txt
+2
-2
@@ -38,8 +38,8 @@ OPTIONS
38
key.
39
40
<format>::
41
- A string that interpolates `%(fieldname)` from the
42
- object pointed at by a ref being shown. If `fieldname`
41
+ A string that interpolates `%(fieldname)` from a ref being shown
42
+ and the object it points at. If `fieldname`
43
is prefixed with an asterisk (`*`) and the ref points
44
at a tag object, the value for the field in the object
45
tag refers is used. When unspecified, defaults to
Documentation/git-tag.txt
+2
-2
@@ -188,8 +188,8 @@ This option is only applicable when listing tags without annotation lines.
188
Defaults to HEAD.
189
190
<format>::
191
- A string that interpolates `%(fieldname)` from the object
192
- pointed at by a ref being shown. The format is the same as
191
+ A string that interpolates `%(fieldname)` from a tag ref being shown
192
+ and the object it points at. The format is the same as
193
that of linkgit:git-for-each-ref[1]. When unspecified,
194
defaults to `%(refname:strip=2)`.
195