{"thread":{"id":"46622","subject":"[PATCH 2/2] Documentation/git-for-each-ref: clarify peeling of tags for --format","startedAt":"2017-08-18T14:51:36Z","lastAt":"2017-08-18T16:53:49Z","messageCount":3,"participants":["Michael J Gruber","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"326691","messageId":"45e7986107a8e8b2f87891c729be8e13043670f3.1503067851.git.git@grubix.eu","threadId":"46622","inReplyTo":"35df94bc16d9b1436d2110f5d5c54732e5d9a619.1503067851.git.git@grubix.eu","subject":"[PATCH 2/2] Documentation/git-for-each-ref: clarify peeling of tags for --format","fromName":"Michael J Gruber","fromEmail":"git@grubix.eu","sentAt":"2017-08-18T14:51:23Z","receivedAt":"2017-08-18T14:51:36Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"`*` in format strings means peeling of tag objects so that object field\nnames refer to the object that the tag object points at, instead of the\ntag object itself.\n\nCurrently, this is documented using grammar that is clearly inspired by\nclassical latin, though missing more than an article in order to be\nclassical english.\n\nTry and straighten that explanation out a bit.\n\nSigned-off-by: Michael J Gruber \n---\n Documentation/git-for-each-ref.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex dac9138fab..bb370c9c7b 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -41,8 +41,9 @@ OPTIONS\n \tA string that interpolates `%(fieldname)` from a ref being shown\n \tand the object it points at. If `fieldname`\n \tis prefixed with an asterisk (`*`) and the ref points\n-\tat a tag object, the value for the field in the object\n-\ttag refers is used. When unspecified, defaults to\n+\tat a tag object, use the value for the field in the object\n+\twhich the tag object refers to (instead of the field in the tag object).\n+\tWhen unspecified, `` defaults to\n \t`%(objectname) SPC %(objecttype) TAB %(refname)`.\n \tIt also interpolates `%%` to `%`, and `%xx` where `xx`\n \tare hex digits interpolates to character with hex code\n-- \n2.14.1.224.g15ee91971c\n\n"},{"id":"326692","messageId":"35df94bc16d9b1436d2110f5d5c54732e5d9a619.1503067851.git.git@grubix.eu","threadId":"46622","inReplyTo":null,"subject":"[PATCH 1/2] Documentation: use proper wording for ref format strings","fromName":"Michael J Gruber","fromEmail":"git@grubix.eu","sentAt":"2017-08-18T14:51:22Z","receivedAt":"2017-08-18T14:51:38Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Various commands list refs and allow to use a format string for the\noutput that interpolates from the ref as well as the object it points\nat (for-each-ref; branch and tag in list mode).\n\nCurrently, the documentation talks about interpolating from the object.\nThis is confusing because a ref points to an object but not vice versa,\nso the object cannot possible know %(refname), for example. Thus, this is\nwrong independent of refs being objects (one day, maybe) or not.\n\nChange the wording to make this clearer (and distinguish it from formats\nfor the log family).\n\nSigned-off-by: Michael J Gruber \n---\n Documentation/git-branch.txt | 4 ++--\n Documentation/git-for-each-ref.txt | 4 ++--\n Documentation/git-tag.txt | 4 ++--\n 3 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex 81bd0a7b77..d0b3358771 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -267,8 +267,8 @@ start-point is either a local or remote-tracking branch.\n \tOnly list branches of the given object.\n \n --format ::\n-\tA string that interpolates `%(fieldname)` from the object\n-\tpointed at by a ref being shown. The format is the same as\n+\tA string that interpolates `%(fieldname)` from a branch ref being shown\n+\tand the object it points at. The format is the same as\n \tthat of linkgit:git-for-each-ref[1].\n \n Examples\ndiff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\nindex cc42c12832..dac9138fab 100644\n--- a/Documentation/git-for-each-ref.txt\n+++ b/Documentation/git-for-each-ref.txt\n@@ -38,8 +38,8 @@ OPTIONS\n \tkey.\n \n ::\n-\tA string that interpolates `%(fieldname)` from the\n-\tobject pointed at by a ref being shown. If `fieldname`\n+\tA string that interpolates `%(fieldname)` from a ref being shown\n+\tand the object it points at. If `fieldname`\n \tis prefixed with an asterisk (`*`) and the ref points\n \tat a tag object, the value for the field in the object\n \ttag refers is used. When unspecified, defaults to\ndiff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt\nindex d97aad3439..543fb425ee 100644\n--- a/Documentation/git-tag.txt\n+++ b/Documentation/git-tag.txt\n@@ -188,8 +188,8 @@ This option is only applicable when listing tags without annotation lines.\n \tDefaults to HEAD.\n \n ::\n-\tA string that interpolates `%(fieldname)` from the object\n-\tpointed at by a ref being shown. The format is the same as\n+\tA string that interpolates `%(fieldname)` from a tag ref being shown\n+\tand the object it points at. The format is the same as\n \tthat of linkgit:git-for-each-ref[1]. When unspecified,\n \tdefaults to `%(refname:strip=2)`.\n \n-- \n2.14.1.224.g15ee91971c\n\n"},{"id":"326699","messageId":"xmqq378oddgp.fsf@gitster.mtv.corp.google.com","threadId":"46622","inReplyTo":"45e7986107a8e8b2f87891c729be8e13043670f3.1503067851.git.git@grubix.eu","subject":"Re: [PATCH 2/2] Documentation/git-for-each-ref: clarify peeling of tags for --format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2017-08-18T16:53:42Z","receivedAt":"2017-08-18T16:53:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> `*` in format strings means peeling of tag objects so that object field\n> names refer to the object that the tag object points at, instead of the\n> tag object itself.\n>\n> Currently, this is documented using grammar that is clearly inspired by\n> classical latin, though missing more than an article in order to be\n> classical english.\n\n;-)\n\nThanks, both patches look good to me.\n\n>\n> Try and straighten that explanation out a bit.\n>\n> Signed-off-by: Michael J Gruber \n> ---\n> Documentation/git-for-each-ref.txt | 5 +++--\n> 1 file changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt\n> index dac9138fab..bb370c9c7b 100644\n> --- a/Documentation/git-for-each-ref.txt\n> +++ b/Documentation/git-for-each-ref.txt\n> @@ -41,8 +41,9 @@ OPTIONS\n> \tA string that interpolates `%(fieldname)` from a ref being shown\n> \tand the object it points at. If `fieldname`\n> \tis prefixed with an asterisk (`*`) and the ref points\n> -\tat a tag object, the value for the field in the object\n> -\ttag refers is used. When unspecified, defaults to\n> +\tat a tag object, use the value for the field in the object\n> +\twhich the tag object refers to (instead of the field in the tag object).\n> +\tWhen unspecified, `` defaults to\n> \t`%(objectname) SPC %(objecttype) TAB %(refname)`.\n> \tIt also interpolates `%%` to `%`, and `%xx` where `xx`\n> \tare hex digits interpolates to character with hex code\n"}]}