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

Junio C Hamano [off-list ref] writes:

Thomas Rast [off-list ref] writes:

quoted

+<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