Re: [PATCH v12 12/13] tag.c: implement '--format' option

> Karthik Nayak <karthik.188@gmail.com> writes:
>
>> --- a/Documentation/git-tag.txt
>> +++ b/Documentation/git-tag.txt
>> @@ -158,6 +159,18 @@ This option is only applicable when listing tags without annotation lines.
>>       The object that the new tag will refer to, usually a commit.
>>       Defaults to HEAD.
>>
>> +<format>::
>> +     A string that interpolates `%(fieldname)` from the object
>> +     pointed at by a ref being shown.  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 `%(refname:short)`.  It also
>> +     interpolates `%%` to `%`, and `%xx` where `xx` are hex digits
>> +     interpolates to character with hex code `xx`; for example
>> +     `%00` interpolates to `\0` (NUL), `%09` to `\t` (TAB) and
>> +     `%0a` to `\n` (LF).  The fields are same as those in `git
>> +     for-each-ref`.
>> +
>
> This documentation should probably be shortened to stg like
>
>         A string that interpolates `%(fieldname)` from the object
>         pointed at by a ref being shown. The format is the same as the
>         one of linkgit:git-for-each-ref[1]. When unspecified, defaults
>         to `%(refname:short)`
>

> Alternatively, you can extract the "FIELD NAMES" section of
> git-for-each-ref.txt to a separate file and include it in the doc for
> each command having this --format option (this is how it's done for "git
> log --format" IIRC). But taking that much space to describe hexadecimal
> escapes that very few people would use and not documenting the %(atoms)
> is counter-productive IMHO.
>

> I would favor the first option (keep it short, include a pointer) with
> Junio's remark in mind: "git tag" and "git branch" are meant to be
> simple commands, and the scary swiss-army-knife should remain "git
> for-each-ref".
>
> I am still (slightly) in favor of adding --format to tag and branch, as
> long as it does not make the commands too scary.
>