On Wed, Aug 19, 2015 at 8:23 PM, Matthieu Moy <Matthieu.Moy@xxxxxxxxxxxxxxx> wrote: > Karthik Nayak <karthik.188@xxxxxxxxx> 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)` > I guess this makes sense with what you're saying below, the --format option for tag.c is more of an extra add-on, and such a discrioption may not be needed. Will change this. > 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 guess, It'll be better to write a document on the whole of ref-filter. I'll probably do that at the end of this. > 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. > Will change this, thanks for the suggestions. -- Regards, Karthik Nayak -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html