deprecate the use of 'hg tag NAME [REV]'

add some tests and some doc

mercurial/commands.py

@@ -2079,10 +2079,16 b' def tag(ui, repo, name, rev_=None, **opt'
     To facilitate version control, distribution, and merging of tags,
     they are stored as a file named ".hgtags" which is managed
     similarly to other project files and can be hand-edited if
-    necessary.
+    necessary.  The file '.hg/localtags' is used for local tags (not
+    shared among repositories).
     """
     if name == "tip":
         raise util.Abort(_("the name 'tip' is reserved"))
+    if rev_ is not None:
+        ui.warn(_("use of 'hg tag NAME [REV]' is deprecated, "
+                  "please use 'hg tag [-r REV] NAME instead\n"))
+        if opts['rev']:
+            raise util.Abort(_("use only one form to specify the revision"))
     if opts['rev']:
         rev_ = opts['rev']
     if rev_:
@@ -2470,7 +2476,7 b' table = {'
           ('d', 'date', '', _('record datecode as commit date')),
           ('u', 'user', '', _('record user as commiter')),
           ('r', 'rev', '', _('revision to tag'))],
-         _('hg tag [OPTION]... NAME [REV]')),
+         _('hg tag [-r REV] [OPTION]... NAME')),
     "tags": (tags, [], _('hg tags')),
     "tip": (tip, [], _('hg tip')),
     "unbundle":

tests/test-tag

@@ -10,6 +10,7 b' hg history'
 
 echo foo >> .hgtags
 hg tag -d "0 0" "bleah2" || echo "failed"
+hg tag -d "0 0" -r 0 "bleah2" 1 || echo "failed"
 
 hg revert .hgtags
 hg tag -d "0 0" -r 0 "bleah0"

tests/test-tag.out

@@ -18,6 +18,10 b' summary: test'
 
 abort: working copy of .hgtags is changed (please commit .hgtags manually)
 failed
+use of 'hg tag NAME [REV]' is deprecated, please use 'hg tag [-r REV] NAME instead
+abort: use only one form to specify the revision
+failed
+use of 'hg tag NAME [REV]' is deprecated, please use 'hg tag [-r REV] NAME instead
 acb14030fe0a21b60322c440ad2d20cf7685a376 bleah
 acb14030fe0a21b60322c440ad2d20cf7685a376 bleah0
 863197ef03781c4fc00276d83eb66c4cb9cd91df bleah1