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>

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b7741f175cf7a99e2aa9cbcacf42da78e..d0b33587717a198655164f5dd5e35e116a8a30e0 100644 (file)
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -267,8 +267,8 @@ start-point is either a local or remote-tracking branch.
        Only list branches of the given object.
 
 --format <format>::
-       A string that interpolates `%(fieldname)` from the object
-       pointed at by a ref being shown.  The format is the same as
+       A string that interpolates `%(fieldname)` from a branch ref being shown
+       and the object it points at.  The format is the same as
        that of linkgit:git-for-each-ref[1].
 
 Examples

diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index 03e187a105b1bd5ffa6e615c2dc9199f0b803e44..f9fa8fa79eebc70d09eb2288c120327e577345d7 100644 (file)
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -38,8 +38,8 @@ OPTIONS
        key.
 
 <format>::
-       A string that interpolates `%(fieldname)` from the
-       object pointed at by a ref being shown.  If `fieldname`
+       A string that interpolates `%(fieldname)` from a ref being shown
+       and the object it points at.  If `fieldname`
        is prefixed with an asterisk (`*`) and the ref points
        at a tag object, the value for the field in the object
        tag refers is used.  When unspecified, defaults to

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index 1eb15afa1ce8a533d65c5f5ace0bcd694d7f6ffd..32410f3d22f0a7961d99854599ea1d5b86e03e07 100644 (file)
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -188,8 +188,8 @@ This option is only applicable when listing tags without annotation lines.
        Defaults to HEAD.
 
 <format>::
-       A string that interpolates `%(fieldname)` from the object
-       pointed at by a ref being shown.  The format is the same as
+       A string that interpolates `%(fieldname)` from a tag ref being shown
+       and the object it points at.  The format is the same as
        that of linkgit:git-for-each-ref[1].  When unspecified,
        defaults to `%(refname:strip=2)`.