Re: [PATCH 3/3] git-tag.txt: document --allow-recursive-tag option

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Tue, Mar 26 2019, Denton Liu wrote:

> Signed-off-by: Denton Liu <liu.denton@gmail.com>
> ---
>  Documentation/git-tag.txt | 7 ++++++-
>  1 file changed, 6 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index a74e7b926d..7e7eb9a7e9 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -10,7 +10,7 @@ SYNOPSIS
>  --------
>  [verse]
>  'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
> -	<tagname> [<commit> | <object>]
> +	[--allow-recursive-tag] <tagname> [<commit> | <object>]
>  'git tag' -d <tagname>...
>  'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
>  	[--points-at <object>] [--column[=<options>] | --no-column]
> @@ -193,6 +193,11 @@ This option is only applicable when listing tags without annotation lines.
>  	that of linkgit:git-for-each-ref[1].  When unspecified,
>  	defaults to `%(refname:strip=2)`.
>
> +--allow-recursive-tag::
> +	Usually recursively tagging a tag object is a mistake and the
> +	command prevents you from making such a tag. This option
> +	bypasses the safety and allows this to happen.
> +
>  <tagname>::
>  	The name of the tag to create, delete, or describe.
>  	The new tag name must pass all checks defined by

Like 1/3 I this should just be squashed into the one patch. No reason to
leave the doc change in another change.

I see the existing --allow-unrelated-histories uses a similar tone, but
maybe something closer to noting that there's nothing wrong with doing
this, and maybe even point out the signed "chain of custody" tagging as
one use-case, then finally noting that since people usually don't really
want this it's disabled by default.

Finally, since "git tag" gets used by scripts a lot in practice, maybe
note that this behavior changed in "Git version 2.22.0".