threads / patch / 46622

patch, 2 partsDocumentation/git-for-each-ref: clarify peeling of tags for --format

Subject: [PATCH 2/2] Documentation/git-for-each-ref: clarify peeling of tags for --format

## tl;dr

3 messages between Aug 18, 2017 and Aug 18, 2017. Diffs are folded; open one to read it.

replies: 2people: 2as markdown or json

Michael J Gruber· Aug 18, 2017, 14:51 UTC · lore

[PATCH 1/2] 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>
---
 Documentation/git-branch.txt       | 4 ++--
 Documentation/git-for-each-ref.txt | 4 ++--
 Documentation/git-tag.txt          | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)
Show changes to 3 files +6 −6

Documentation/git-branch.txt, Documentation/git-for-each-ref.txt, Documentation/git-tag.txt

diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index 81bd0a7b77..d0b3358771 100644
--- 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 cc42c12832..dac9138fab 100644
--- 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 d97aad3439..543fb425ee 100644
--- 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)`.
 

-- 
2.14.1.224.g15ee91971c
Michael J Gruber· Aug 18, 2017, 14:51 UTC · re: Michael J Gruber · lore

`*` in format strings means peeling of tag objects so that object field names refer to the object that the tag object points at, instead of the tag object itself.

Currently, this is documented using grammar that is clearly inspired by classical latin, though missing more than an article in order to be classical english.

Try and straighten that explanation out a bit.
Signed-off-by: Michael J Gruber <git@grubix.eu>
---
 Documentation/git-for-each-ref.txt | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)
Show changes to Documentation/git-for-each-ref.txt +3 −2
diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
index dac9138fab..bb370c9c7b 100644
--- a/Documentation/git-for-each-ref.txt
+++ b/Documentation/git-for-each-ref.txt
@@ -41,8 +41,9 @@ OPTIONS
 	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
+	at a tag object, use the value for the field in the object
+	which the tag object refers to (instead of the field in the tag object).
+	When unspecified, `<format>` defaults to
 	`%(objectname) SPC %(objecttype) TAB %(refname)`.
 	It also interpolates `%%` to `%`, and `%xx` where `xx`
 	are hex digits interpolates to character with hex code

-- 
2.14.1.224.g15ee91971c
Junio C Hamano· Aug 18, 2017, 16:53 UTC · re: Michael J Gruber · lore

Re: [PATCH 2/2] Documentation/git-for-each-ref: clarify peeling of tags for --format

Michael J Gruber <git@grubix.eu> writes:
Show 7 quoted lines
> `*` in format strings means peeling of tag objects so that object field
> names refer to the object that the tag object points at, instead of the
> tag object itself.
>
> Currently, this is documented using grammar that is clearly inspired by
> classical latin, though missing more than an article in order to be
> classical english.
;-)
Thanks, both patches look good to me.
Show 24 quoted lines
>
> Try and straighten that explanation out a bit.
>
> Signed-off-by: Michael J Gruber <git@grubix.eu>
> ---
>  Documentation/git-for-each-ref.txt | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt
> index dac9138fab..bb370c9c7b 100644
> --- a/Documentation/git-for-each-ref.txt
> +++ b/Documentation/git-for-each-ref.txt
> @@ -41,8 +41,9 @@ OPTIONS
>  	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
> +	at a tag object, use the value for the field in the object
> +	which the tag object refers to (instead of the field in the tag object).
> +	When unspecified, `<format>` defaults to
>  	`%(objectname) SPC %(objecttype) TAB %(refname)`.
>  	It also interpolates `%%` to `%`, and `%xx` where `xx`
>  	are hex digits interpolates to character with hex code

← back to recent threads