commitizen-tools · yjaw · Jan 27, 2026 · Jan 27, 2026
@@ -541,6 +541,12 @@ def __call__(
                         "action": "store_true",
                         "exclusive_group": "group1",
                     },
+                    {
+                        "name": ["--tag"],
+                        "help": "get the version with tag prefix",
+                        "action": "store_true",
+                        "exclusive_group": "group2",
+                    },
                     {
                         "name": ["--major"],
                         "help": "get just the major version. Need to be used with --project or --verbose.",

@@ -7,6 +7,7 @@
 from commitizen.config import BaseConfig
 from commitizen.exceptions import NoVersionSpecifiedError, VersionSchemeUnknown
 from commitizen.providers import get_provider
+from commitizen.tags import TagRules
 from commitizen.version_schemes import get_version_scheme
 
 
@@ -17,6 +18,7 @@ class VersionArgs(TypedDict, total=False):
     verbose: bool
     major: bool
     minor: bool
+    tag: bool
 
 
 class Version:
@@ -59,6 +61,9 @@ def __call__(self) -> None:
                 version = f"{version_scheme.major}"
             elif self.arguments.get("minor"):
                 version = f"{version_scheme.minor}"
+            elif self.arguments.get("tag"):
+                tag_rules = TagRules.from_settings(self.config.settings)
+                version = tag_rules.normalize_tag(version_scheme)
 
             out.write(
                 f"Project Version: {version}"
@@ -67,10 +72,14 @@ def __call__(self) -> None:
             )
             return
 
-        if self.arguments.get("major") or self.arguments.get("minor"):
-            out.error(
-                "Major or minor version can only be used with --project or --verbose."
-            )
+        if self.arguments.get("major"):
+            out.error("Major can only be used with --project or --verbose.")
+            return
+        if self.arguments.get("minor"):
+            out.error("Minor can only be used with --project or --verbose.")
+            return
+        if self.arguments.get("tag"):
+            out.error("Tag can only be used with --project or --verbose.")
             return
 
         # If no arguments are provided, just show the installed commitizen version

@@ -1,4 +1,4 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v] [--tag | --major | --minor]
 
 get the version of the installed commitizen or the current project (default:
 installed commitizen)
@@ -10,6 +10,7 @@ options:
   -c, --commitizen  get the version of the installed commitizen
   -v, --verbose     get the version of both the installed commitizen and the
                     current project
+  --tag             get the version with tag prefix
   --major           get just the major version. Need to be used with --project
                     or --verbose.
   --minor           get just the minor version. Need to be used with --project

@@ -1,4 +1,4 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v] [--tag | --major | --minor]
 
 get the version of the installed commitizen or the current project (default:
 installed commitizen)
@@ -10,6 +10,7 @@ options:
   -c, --commitizen  get the version of the installed commitizen
   -v, --verbose     get the version of both the installed commitizen and the
                     current project
+  --tag             get the version with tag prefix
   --major           get just the major version. Need to be used with --project
                     or --verbose.
   --minor           get just the minor version. Need to be used with --project

@@ -1,4 +1,4 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v] [--tag | --major | --minor]
 
 get the version of the installed commitizen or the current project (default:
 installed commitizen)
@@ -10,6 +10,7 @@ options:
   -c, --commitizen  get the version of the installed commitizen
   -v, --verbose     get the version of both the installed commitizen and the
                     current project
+  --tag             get the version with tag prefix
   --major           get just the major version. Need to be used with --project
                     or --verbose.
   --minor           get just the minor version. Need to be used with --project

@@ -1,4 +1,4 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v] [--tag | --major | --minor]
 
 get the version of the installed commitizen or the current project (default:
 installed commitizen)
@@ -10,6 +10,7 @@ options:
   -c, --commitizen  get the version of the installed commitizen
   -v, --verbose     get the version of both the installed commitizen and the
                     current project
+  --tag             get the version with tag prefix
   --major           get just the major version. Need to be used with --project
                     or --verbose.
   --minor           get just the minor version. Need to be used with --project

@@ -1,4 +1,4 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v] [--tag | --major | --minor]
 
 get the version of the installed commitizen or the current project (default:
 installed commitizen)
@@ -10,6 +10,7 @@ options:
   -c, --commitizen  get the version of the installed commitizen
   -v, --verbose     get the version of both the installed commitizen and the
                     current project
+  --tag             get the version with tag prefix
   --major           get just the major version. Need to be used with --project
                     or --verbose.
   --minor           get just the minor version. Need to be used with --project

@@ -147,17 +147,66 @@ def test_version_just_minor(config, capsys, version: str, expected_version: str)
     assert expected_version == captured.out
 
 
-@pytest.mark.parametrize("argument", ("major", "minor"))
-def test_version_just_major_error_no_project(config, capsys, argument: str):
+def test_version_major_error_no_project(config, capsys):
+    """Test --major requires --project or --verbose"""
     commands.Version(
         config,
         {
-            argument: True,  # type: ignore[misc]
+            "major": True,
         },
     )()
     captured = capsys.readouterr()
     assert not captured.out
-    assert (
-        "Major or minor version can only be used with --project or --verbose."
-        in captured.err
-    )
+    assert "Major can only be used with --project or --verbose." in captured.err
+
+
+def test_version_minor_error_no_project(config, capsys):
+    """Test --minor requires --project or --verbose"""
+    commands.Version(
+        config,
+        {
+            "minor": True,
+        },
+    )()
+    captured = capsys.readouterr()
+    assert not captured.out
+    assert "Minor can only be used with --project or --verbose." in captured.err
+
+
+def test_version_tag_error_no_project(config, capsys):
+    """Test --tag requires --project or --verbose"""
+    commands.Version(
+        config,
+        {
+            "tag": True,
+        },
+    )()
+    captured = capsys.readouterr()
+    assert not captured.out
+    assert "Tag can only be used with --project or --verbose." in captured.err
+
+
+@pytest.mark.parametrize(
+    "version, tag_format, expected_output",
+    [
+        ("1.2.3", "v$version", "v1.2.3\n"),
+        ("1.2.3", "$version", "1.2.3\n"),
+        ("2.0.0", "release-$version", "release-2.0.0\n"),
+        ("0.1.0", "ver$version", "ver0.1.0\n"),
+    ],
+)
+def test_version_with_tag_format(
+    config, capsys, version: str, tag_format: str, expected_output: str
+):
+    """Test --tag option applies tag_format to version"""
+    config.settings["version"] = version
+    config.settings["tag_format"] = tag_format
+    commands.Version(
+        config,
+        {
+            "project": True,
+            "tag": True,
+        },
+    )()
+    captured = capsys.readouterr()
+    assert captured.out == expected_output