# [PATCH] git-tag(1): we tag HEAD by default

8 messages from 2013-04-03 to 2013-04-03. Participants: Thomas Rast, Junio C Hamano, Yann Droneaud.
Thread: https://gitlist.dev/t/33365

## Thomas Rast, 2013-04-03 14:27

Subject: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <137ebfa428b16497287c55e552372df1087f1588.1364999181.git.trast@inf.ethz.ch>
URL: https://gitlist.dev/e/137ebfa428b16497287c55e552372df1087f1588.1364999181.git.trast%40inf.ethz.ch

```
The <commit>|<object> argument is actually not explained anywhere
(except implicitly in the description of an unannotated tag).  Write a
little explanation, in particular to cover the default.

Signed-off-by: Thomas Rast <trast@inf.ethz.ch>
---

Prompted by a question on IRC about the default value.  Do we actually
read our own docs? ;-)

 Documentation/git-tag.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
index e3032c4..697df50 100644
--- a/Documentation/git-tag.txt
+++ b/Documentation/git-tag.txt
@@ -126,6 +126,11 @@ This option is only applicable when listing tags without annotation lines.
 	linkgit:git-check-ref-format[1].  Some of these checks
 	may restrict the characters allowed in a tag name.
 
+<commit>, <object>::
+	The object that the new tag will refer to, usually a commit.
+	Defaults to HEAD.
+
+
 CONFIGURATION
 -------------
 By default, 'git tag' in sign-with-default mode (-s) will use your
-- 
1.8.2.548.g7173465

```

## Junio C Hamano, 2013-04-03 15:04

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <7vzjxf64gn.fsf@alter.siamese.dyndns.org>
URL: https://gitlist.dev/e/7vzjxf64gn.fsf%40alter.siamese.dyndns.org
In-Reply-To: <137ebfa428b16497287c55e552372df1087f1588.1364999181.git.trast@inf.ethz.ch>

```
Thomas Rast <trast@inf.ethz.ch> writes:

> The <commit>|<object> argument is actually not explained anywhere
> (except implicitly in the description of an unannotated tag).  Write a
> little explanation, in particular to cover the default.
>
> Signed-off-by: Thomas Rast <trast@inf.ethz.ch>
> ---
>
> Prompted by a question on IRC about the default value.  Do we actually
> read our own docs? ;-)

Perhaps among us some of them are real men ;-)

>  Documentation/git-tag.txt | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt
> index e3032c4..697df50 100644
> --- a/Documentation/git-tag.txt
> +++ b/Documentation/git-tag.txt
> @@ -126,6 +126,11 @@ This option is only applicable when listing tags without annotation lines.
>  	linkgit:git-check-ref-format[1].  Some of these checks
>  	may restrict the characters allowed in a tag name.
>  
> +<commit>, <object>::
> +	The object that the new tag will refer to, usually a commit.
> +	Defaults to HEAD.

Shouldn't this be more like this:

    <commit>::
    <object>::
	Your explanation here...

Other than that, I think this is a reasonable change.
Thanks.

> +
> +
>  CONFIGURATION
>  -------------
>  By default, 'git tag' in sign-with-default mode (-s) will use your

```

## Thomas Rast, 2013-04-03 15:11

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <877gkjvecg.fsf@linux-k42r.v.cablecom.net>
URL: https://gitlist.dev/e/877gkjvecg.fsf%40linux-k42r.v.cablecom.net
In-Reply-To: <7vzjxf64gn.fsf@alter.siamese.dyndns.org>

```
Junio C Hamano <gitster@pobox.com> writes:

> Thomas Rast <trast@inf.ethz.ch> writes:
>
>> +<commit>, <object>::
>> +	The object that the new tag will refer to, usually a commit.
>> +	Defaults to HEAD.
>
> Shouldn't this be more like this:
>
>     <commit>::
>     <object>::
> 	Your explanation here...

Hmm, you're right, but we seem to be fairly inconsistent in that
department.  There are some instances with the comma style:

  $ git grep ',.*::$' Documentation/*.txt
  Documentation/blame-options.txt:-L <start>,<end>, -L :<regex>::                                        
  Documentation/config.txt:gitcvs.dbuser, gitcvs.dbpass::                                                
  Documentation/config.txt:http.lowSpeedLimit, http.lowSpeedTime::                                       
  Documentation/diff-options.txt:--stat[=<width>[,<name-width>[,<count>]]]::                             
  Documentation/diff-options.txt:--dirstat[=<param1,param2,...>]::                                       
  Documentation/git-add.txt:-e, \--edit::                                                                
  Documentation/git-check-attr.txt:-a, --all::                                                           
  Documentation/git-check-ignore.txt:-q, --quiet::                                                       
  Documentation/git-check-ignore.txt:-v, --verbose::                                                     
  Documentation/git-index-pack.txt:--index-version=<version>[,<offset>]::                                
  Documentation/git-log.txt:-L <start>,<end>:<file>, -L :<regex>:<file>::                                
  Documentation/git-log.txt:git log -L '/int main/',/^}/:main.c::                                        
  Documentation/git-p4.txt:--verbose, -v::                                                               
  Documentation/git-p4.txt:--dry-run, -n::                                                               
  Documentation/git-p4.txt:"//depot/my/project@1,6"::                                                    
  Documentation/git-pack-objects.txt:--index-version=<version>[,<offset>]::                              
  Documentation/git-remote-fd.txt:`git push fd::7,8 master (as URL)`::                                   
  Documentation/git-remote-fd.txt:`git push fd::7,8/bar master`::
  Documentation/git-reset.txt:Undo a commit, making it a topic branch::
  Documentation/git-shortlog.txt:-w[<width>[,<indent1>[,<indent2>]]]::
  Documentation/git-show-branch.txt:--reflog[=<n>[,<base>]] [<ref>]::
  Documentation/git-tag.txt:<commit>, <object>::
  Documentation/revisions.txt:'<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
  Documentation/revisions.txt:'<describeOutput>', e.g. 'v1.7.4.2-679-g3bee7fb'::
  Documentation/revisions.txt:'<refname>', e.g. 'master', 'heads/master', 'refs/heads/master'::
  Documentation/revisions.txt:'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\
  Documentation/revisions.txt:'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
  Documentation/revisions.txt:'@\{<n>\}', e.g. '@\{1\}'::
  Documentation/revisions.txt:'@\{-<n>\}', e.g. '@\{-1\}'::
  Documentation/revisions.txt:'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
  Documentation/revisions.txt:'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
  Documentation/revisions.txt:'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
  Documentation/revisions.txt:'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
  Documentation/revisions.txt:'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
  Documentation/revisions.txt:'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}'::
  Documentation/revisions.txt:':/<text>', e.g. ':/fix nasty bug'::
  Documentation/revisions.txt:'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
  Documentation/revisions.txt:':<n>:<path>', e.g. ':0:README', ':README'::
  Documentation/revisions.txt:'<rev>{caret}@', e.g. 'HEAD{caret}@'::
  Documentation/revisions.txt:'<rev>{caret}!', e.g. 'HEAD{caret}!'::

But the majority uses the two-line style:

  $ git grep -A1 '::$' Documentation/*.txt | egrep '^--$|::$' | perl -ne '$lastbreak=$. if /^--/; if ($lastbreak<$.-1) {print "$last$_"; $last="";} else {$last=$_;}'
  Documentation/blame-options.txt:-p::
  Documentation/blame-options.txt:--porcelain::
  Documentation/config.txt:add.ignore-errors::
  Documentation/config.txt:add.ignoreErrors::
  Documentation/config.txt:format.to::
  Documentation/config.txt:format.cc::
  Documentation/config.txt:gc.reflogexpire::
  Documentation/config.txt:gc.<pattern>.reflogexpire::
  Documentation/config.txt:gc.reflogexpireunreachable::
  Documentation/config.txt:gc.<ref>.reflogexpireunreachable::
  Documentation/config.txt:gitweb.category::
  Documentation/config.txt:gitweb.description::
  [snip 800+ more lines]

Should we fix that?

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

```

## Junio C Hamano, 2013-04-03 15:17

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <7vvc8363v7.fsf@alter.siamese.dyndns.org>
URL: https://gitlist.dev/e/7vvc8363v7.fsf%40alter.siamese.dyndns.org
In-Reply-To: <877gkjvecg.fsf@linux-k42r.v.cablecom.net>

```
Thomas Rast <trast@inf.ethz.ch> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Thomas Rast <trast@inf.ethz.ch> writes:
>>
>>> +<commit>, <object>::
>>> +	The object that the new tag will refer to, usually a commit.
>>> +	Defaults to HEAD.
>>
>> Shouldn't this be more like this:
>>
>>     <commit>::
>>     <object>::
>> 	Your explanation here...
>
> Hmm, you're right, but we seem to be fairly inconsistent in that
> department.  There are some instances with the comma style:

That is because we did not know better in the olden days, until
somebody noticed and started using the separate-line form.  We might
have a patch or two to only convert from the comma-style but I do
not recall us doing a whole-tree style clean-ups.

> Should we fix that?

I personally do not think the churn is warranted.  "Fix the existing
ones you notice as you touch the vicinity, and avoid introducing new
ones" is good enough.

```

## Yann Droneaud, 2013-04-03 15:18

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <3b24bc742b9738531d707932a9775c98@meuh.org>
URL: https://gitlist.dev/e/3b24bc742b9738531d707932a9775c98%40meuh.org
In-Reply-To: <137ebfa428b16497287c55e552372df1087f1588.1364999181.git.trast@inf.ethz.ch>

```
Hi,

Le 03.04.2013 16:27, Thomas Rast a écrit :
> The <commit>|<object> argument is actually not explained anywhere
> (except implicitly in the description of an unannotated tag).  Write 
> a
> little explanation, in particular to cover the default.

> +<commit>, <object>::
> +	The object that the new tag will refer to, usually a commit.
> +	Defaults to HEAD.
> +
> +

This puzzled me a lot, so I try various configuration:
- I was able to create an annotated tag on an annotated tag (this can 
be recursively)

   git tag -a -m "tagged a tag" test_tag_tag v1.8.2
   git show test_tag_tag

- I was able to tag a file

   git tag -a -m "tagged a file" test_tag_file `git ls-tree HEAD | awk 
'{ print $3; exit; }'`
   git show test_tag_file
   git show -p test_tag_file


Is there any other kind of object that can be tagged ... and what is 
the purpose of this ?


Regards.

-- 
Yann Droneaud
OPTEYA

```

## Thomas Rast, 2013-04-03 15:22

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <87k3ojtz9n.fsf@linux-k42r.v.cablecom.net>
URL: https://gitlist.dev/e/87k3ojtz9n.fsf%40linux-k42r.v.cablecom.net
In-Reply-To: <3b24bc742b9738531d707932a9775c98@meuh.org>

```
Yann Droneaud <ydroneaud@opteya.com> writes:

> Hi,
>
> Le 03.04.2013 16:27, Thomas Rast a écrit :
>> +<commit>, <object>::
>> +	The object that the new tag will refer to, usually a commit.
>> +	Defaults to HEAD.
> 
> Is there any other kind of object that can be tagged ... and what is
> the purpose of this ?

Any object type, including tags.  Signed tags of other tags probably
make sense if you want to express extra approval on top of the original
signature.

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

```

## Junio C Hamano, 2013-04-03 18:20

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <7v7gkj5vcm.fsf@alter.siamese.dyndns.org>
URL: https://gitlist.dev/e/7v7gkj5vcm.fsf%40alter.siamese.dyndns.org
In-Reply-To: <877gkjvecg.fsf@linux-k42r.v.cablecom.net>

```
Thomas Rast <trast@inf.ethz.ch> writes:

> There are some instances with the comma style:
>
>   $ git grep ',.*::$' Documentation/*.txt
>   Documentation/blame-options.txt:-L <start>,<end>, -L :<regex>::
>   Documentation/config.txt:gitcvs.dbuser, gitcvs.dbpass::
>   Documentation/config.txt:http.lowSpeedLimit, http.lowSpeedTime::
>   Documentation/git-add.txt:-e, \--edit::
>   Documentation/git-check-attr.txt:-a, --all::
>   Documentation/git-check-ignore.txt:-q, --quiet::
>   Documentation/git-check-ignore.txt:-v, --verbose::
>   Documentation/git-log.txt:-L <start>,<end>:<file>, -L :<regex>:<file>::
>   Documentation/git-p4.txt:--verbose, -v::
>   Documentation/git-p4.txt:--dry-run, -n::
>   Documentation/git-tag.txt:<commit>, <object>::

The above are clearly candidate for clean-ups (the last one is your
making I already killed in this thread, isn't it?).

These are false matches, I think.

>   Documentation/diff-options.txt:--stat[=<width>[,<name-width>[,<count>]]]::
>   Documentation/diff-options.txt:--dirstat[=<param1,param2,...>]::
>   Documentation/git-index-pack.txt:--index-version=<version>[,<offset>]::
>   Documentation/git-log.txt:git log -L '/int main/',/^}/:main.c::
>   Documentation/git-p4.txt:"//depot/my/project@1,6"::
>   Documentation/git-pack-objects.txt:--index-version=<version>[,<offset>]::
>   Documentation/git-remote-fd.txt:`git push fd::7,8 master (as URL)`::
>   Documentation/git-remote-fd.txt:`git push fd::7,8/bar master`::
>   Documentation/git-reset.txt:Undo a commit, making it a topic branch::
>   Documentation/git-shortlog.txt:-w[<width>[,<indent1>[,<indent2>]]]::
>   Documentation/git-show-branch.txt:--reflog[=<n>[,<base>]] [<ref>]::

I am not sure about these "A, e.g. B, C::" entries.  I tend to think
that they are all logically a single entry, that happen to have
commas in their entry heading, and fall into the same "false
matches" category as above.

>   Documentation/revisions.txt:'<sha1>', e.g. 'dae86e1950b1277e545cee180551750029cfe735', 'dae86e'::
>   Documentation/revisions.txt:'<describeOutput>', e.g. 'v1.7.4.2-679-g3bee7fb'::
>   Documentation/revisions.txt:'<refname>', e.g. 'master', 'heads/master', 'refs/heads/master'::
>   Documentation/revisions.txt:'<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\
>   Documentation/revisions.txt:'<refname>@\{<n>\}', e.g. 'master@\{1\}'::
>   Documentation/revisions.txt:'@\{<n>\}', e.g. '@\{1\}'::
>   Documentation/revisions.txt:'@\{-<n>\}', e.g. '@\{-1\}'::
>   Documentation/revisions.txt:'<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}'::
>   Documentation/revisions.txt:'<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0'::
>   Documentation/revisions.txt:'<rev>{tilde}<n>', e.g. 'master{tilde}3'::
>   Documentation/revisions.txt:'<rev>{caret}\{<type>\}', e.g. 'v0.99.8{caret}\{commit\}'::
>   Documentation/revisions.txt:'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
>   Documentation/revisions.txt:'<rev>{caret}\{/<text>\}', e.g. 'HEAD^{/fix nasty bug}'::
>   Documentation/revisions.txt:':/<text>', e.g. ':/fix nasty bug'::
>   Documentation/revisions.txt:'<rev>:<path>', e.g. 'HEAD:README', ':README', 'master:./README'::
>   Documentation/revisions.txt:':<n>:<path>', e.g. ':0:README', ':README'::
>   Documentation/revisions.txt:'<rev>{caret}@', e.g. 'HEAD{caret}@'::
>   Documentation/revisions.txt:'<rev>{caret}!', e.g. 'HEAD{caret}!'::

```

## Junio C Hamano, 2013-04-03 18:21

Subject: Re: [PATCH] git-tag(1): we tag HEAD by default
Message-ID: <7v38v75vaz.fsf@alter.siamese.dyndns.org>
URL: https://gitlist.dev/e/7v38v75vaz.fsf%40alter.siamese.dyndns.org
In-Reply-To: <87k3ojtz9n.fsf@linux-k42r.v.cablecom.net>

```
Thomas Rast <trast@inf.ethz.ch> writes:

> Yann Droneaud <ydroneaud@opteya.com> writes:
> ...
>> Is there any other kind of object that can be tagged ... and what is
>> the purpose of this ?
>
> Any object type, including tags.  Signed tags of other tags probably
> make sense if you want to express extra approval on top of the original
> signature.

I looked at what "git show" implements, and it seems to peel each
level of tags to show all of them, which is very good.

```