Karthik Nayak <karthik....@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/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
