Allow creating annotated tags

When creating annotated tags (by passing a message into them), you can
use "git describe".

This is based on work by @gvangool.

.bumpversion.cfg

@@ -1,6 +1,7 @@
 [bumpversion]
 commit = True
 tag = True
+tag_message = "bumpversion {new_version}"
 current_version = 0.5.1-dev
 parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(\-(?P<release>[a-z]+))?
 serialize = 

bumpversion/__init__.py

@@ -146,8 +146,11 @@ def add_path(cls, path):
         subprocess.check_output(["git", "add", "--update", path])
 
     @classmethod
-    def tag(cls, name):
-        subprocess.check_output(["git", "tag", name])
+    def tag(cls, name, message):
+        command = ["git", "tag", name]
+        if message:
+            command += ['-m', message]
+        subprocess.check_output(command)
 
 
 class Mercurial(BaseVCS):
@@ -178,8 +181,11 @@ def add_path(cls, path):
         pass
 
     @classmethod
-    def tag(cls, name):
-        subprocess.check_output(["hg", "tag", name])
+    def tag(cls, name, message):
+        command = ["hg", "tag", name]
+        if message:
+            command += ['-m', message]
+        subprocess.check_output(command)
 
 VCS = [Git, Mercurial]
 
@@ -572,6 +578,7 @@ def serialize(self, version, context):
     '--search',
     '--replace',
     '--tag-name',
+    '--tag-message',
 ]
 
 
@@ -855,11 +862,13 @@ def main(original_args=None):
                          help='Tag name (only works with --tag)',
                          default=defaults.get('tag_name', 'v{new_version}'))
 
+    parser3.add_argument('--tag-message', metavar='TAG_MESSAGE', dest='tag_message',
+                         help='Tag message', default=defaults.get('tag_message', ''))
+
     parser3.add_argument('--message', '-m', metavar='COMMIT_MSG',
                          help='Commit message',
                          default=defaults.get('message', 'Bump version: {current_version} → {new_version}'))
 
-
     file_names = []
     if 'files' in defaults:
         assert defaults['files'] != None
@@ -989,12 +998,13 @@ def main(original_args=None):
         vcs.commit(message=commit_message)
 
     tag_name = args.tag_name.format(**vcs_context)
-    logger.info("{} '{}' in {}".format(
+    tag_message = args.tag_message.format(**vcs_context)
+    logger.info("{} '{}' {} in {}".format(
         "Would tag" if not do_tag else "Tagging",
         tag_name,
+        "with message '{}'".format(tag_message) if tag_message else "without message",
         vcs.__name__
     ))
 
     if do_tag:
-        vcs.tag(tag_name)
-
+        vcs.tag(tag_name, tag_message)

tests.py

@@ -66,7 +66,8 @@ def _mock_calls_to_string(called_mock):
                [--parse REGEX] [--serialize FORMAT] [--search SEARCH]
                [--replace REPLACE] [--current-version VERSION] [--dry-run]
                --new-version VERSION [--commit | --no-commit]
-               [--tag | --no-tag] [--tag-name TAG_NAME] [--message COMMIT_MSG]
+               [--tag | --no-tag] [--tag-name TAG_NAME]
+               [--tag-message TAG_MESSAGE] [--message COMMIT_MSG]
                part [file [file ...]]
 
 %s
@@ -103,6 +104,8 @@ def _mock_calls_to_string(called_mock):
   --no-tag              Do not create a tag in version control
   --tag-name TAG_NAME   Tag name (only works with --tag) (default:
                         v{new_version})
+  --tag-message TAG_MESSAGE
+                        Tag message (default: )
   --message COMMIT_MSG, -m COMMIT_MSG
                         Commit message (default: Bump version:
                         {current_version} → {new_version})
@@ -708,6 +711,80 @@ def test_message_from_config_file(tmpdir, capsys, vcs):
 
     assert b'from-400.0.0-to-401.0.0' in tag_out
 
+
+@pytest.mark.parametrize(("vcs"), [xfail_if_no_git("git"), xfail_if_no_hg("hg")])
+def test_unannotated_tag(tmpdir, vcs):
+    tmpdir.chdir()
+    check_call([vcs, "init"])
+    tmpdir.join("VERSION").write("42.3.1")
+    check_call([vcs, "add", "VERSION"])
+    check_call([vcs, "commit", "-m", "initial commit"])
+
+    main(['patch', '--current-version', '42.3.1', '--commit', '--tag', 'VERSION', '--tag-name', 'ReleasedVersion-{new_version}'])
+
+    tag_out = check_output([vcs, {"git": "tag", "hg": "tags"}[vcs]])
+    assert b'ReleasedVersion-42.3.2' in tag_out
+
+    if vcs == "git":
+        describe_out = subprocess.call([vcs, "describe"])
+        assert 128 == describe_out
+
+        describe_out = subprocess.check_output([vcs, "describe", "--tags"])
+        assert describe_out.startswith(b'ReleasedVersion-42.3.2')
+
+
+@pytest.mark.parametrize(("vcs"), [xfail_if_no_git("git"), xfail_if_no_hg("hg")])
+def test_annotated_tag(tmpdir, vcs):
+    tmpdir.chdir()
+    check_call([vcs, "init"])
+    tmpdir.join("VERSION").write("42.4.1")
+    check_call([vcs, "add", "VERSION"])
+    check_call([vcs, "commit", "-m", "initial commit"])
+
+    main(['patch', '--current-version', '42.4.1', '--commit', '--tag', 'VERSION', '--tag-message', 'test {new_version}-tag'])
+    assert '42.4.2' == tmpdir.join("VERSION").read()
+
+    tag_out = check_output([vcs, {"git": "tag", "hg": "tags"}[vcs]])
+    assert b'v42.4.2' in tag_out
+
+    if vcs == "git":
+        describe_out = subprocess.check_output([vcs, "describe"])
+        assert describe_out == b'v42.4.2\n'
+
+        describe_out = subprocess.check_output([vcs, "show", "v42.4.2"])
+        assert describe_out.startswith(b"tag v42.4.2\n")
+        assert b'test 42.4.2-tag' in describe_out
+    elif vcs == "hg":
+        describe_out = subprocess.check_output([vcs, "log"])
+        assert b'test 42.4.2-tag' in describe_out
+    else:
+        raise ValueError("Unknown VCS")
+
+
+@pytest.mark.parametrize(("vcs"), [xfail_if_no_git("git")])
+def test_vcs_describe(tmpdir, vcs):
+    tmpdir.chdir()
+    check_call([vcs, "init"])
+    tmpdir.join("VERSION").write("42.5.1")
+    check_call([vcs, "add", "VERSION"])
+    check_call([vcs, "commit", "-m", "initial commit"])
+
+    main(['patch', '--current-version', '42.5.1', '--commit', '--tag', 'VERSION', '--tag-message', 'test {new_version}-tag'])
+    assert '42.5.2' == tmpdir.join("VERSION").read()
+
+    describe_out = subprocess.check_output([vcs, "describe"])
+    assert b'v42.5.2\n' == describe_out
+
+    main(['patch', '--current-version', '42.5.2', '--commit', '--tag', 'VERSION', '--tag-name', 'ReleasedVersion-{new_version}'])
+    assert '42.5.3' == tmpdir.join("VERSION").read()
+
+    describe_out = subprocess.check_output([vcs, "describe"])
+    assert describe_out.startswith(b'v42.5.2-1-g')
+
+    describe_out = subprocess.check_output([vcs, "describe", "--tags"])
+    assert b'ReleasedVersion-42.5.3\n' == describe_out
+
+
 config_parser_handles_utf8 = True
 try:
     import configparser
@@ -1051,7 +1128,7 @@ def test_subjunctive_dry_run_logging(tmpdir, vcs):
         info|Would add changes in file 'dont_touch_me.txt' to Git|
         info|Would add changes in file '.bumpversion.cfg' to Git|
         info|Would commit to Git with message 'Bump version: 0.8 \u2192 0.8.1'|
-        info|Would tag 'v0.8.1' in Git|
+        info|Would tag 'v0.8.1' without message in Git|
         """).strip()
 
     if vcs == "hg":
@@ -1115,7 +1192,7 @@ def test_log_commitmessage_if_no_commit_tag_but_usable_vcs(tmpdir, vcs):
         info|Would add changes in file 'please_touch_me.txt' to Git|
         info|Would add changes in file '.bumpversion.cfg' to Git|
         info|Would commit to Git with message 'Bump version: 0.3.3 \u2192 0.3.4'|
-        info|Would tag 'v0.3.4' in Git|
+        info|Would tag 'v0.3.4' without message in Git|
         """).strip()
 
     if vcs == "hg":