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

[Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>]

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.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/