feat(version): add MANUAL_VERSION, --next and --patch to version command

bearomorphism · bearomorphism · commit 4b6a4411f9c6 · 2026-01-06T21:56:34.000+08:00
diff --git a/commitizen/cli.py b/commitizen/cli.py
@@ -20,6 +20,7 @@
     InvalidCommandArgumentError,
     NoCommandFoundError,
 )
+from commitizen.version_increment import VersionIncrement
 
 logger = logging.getLogger(__name__)
 
@@ -505,54 +506,79 @@ def __call__(
             {
                 "name": ["version"],
                 "description": (
-                    "get the version of the installed commitizen or the current project"
-                    " (default: installed commitizen)"
+                    "Shows version of Commitizen or the version of the current project. "
+                    "Combine with other options to simulate the version increment process and play with the selected version scheme. "
+                    "If no arguments are provided, just show the installed Commitizen version."
                 ),
                 "help": (
-                    "get the version of the installed commitizen or the current project"
-                    " (default: installed commitizen)"
+                    "Shows version of Commitizen or the version of the current project. "
+                    "Combine with other options to simulate the version increment process and play with the selected version scheme."
                 ),
                 "func": commands.Version,
                 "arguments": [
                     {
                         "name": ["-r", "--report"],
-                        "help": "get system information for reporting bugs",
+                        "help": "Get system information for reporting bugs",
                         "action": "store_true",
                         "exclusive_group": "group1",
                     },
                     {
                         "name": ["-p", "--project"],
-                        "help": "get the version of the current project",
+                        "help": "Get the version of the current project",
                         "action": "store_true",
                         "exclusive_group": "group1",
                     },
                     {
                         "name": ["-c", "--commitizen"],
-                        "help": "get the version of the installed commitizen",
+                        "help": "Get the version of the installed commitizen",
                         "action": "store_true",
                         "exclusive_group": "group1",
                     },
                     {
                         "name": ["-v", "--verbose"],
                         "help": (
-                            "get the version of both the installed commitizen "
+                            "Get the version of both the installed commitizen "
                             "and the current project"
                         ),
                         "action": "store_true",
                         "exclusive_group": "group1",
                     },
                     {
                         "name": ["--major"],
-                        "help": "get just the major version. Need to be used with --project or --verbose.",
+                        "help": "Output the major version only. Need to be used with MANUAL_VERSION, --project or --verbose.",
                         "action": "store_true",
                         "exclusive_group": "group2",
                     },
                     {
                         "name": ["--minor"],
-                        "help": "get just the minor version. Need to be used with --project or --verbose.",
+                        "help": "Output the minor version only. Need to be used with MANUAL_VERSION, --project or --verbose.",
                         "action": "store_true",
                         "exclusive_group": "group2",
                     },
+                    {
+                        "name": ["--patch"],
+                        "help": "Output the patch version only. Need to be used with MANUAL_VERSION, --project or --verbose.",
+                        "action": "store_true",
+                        "exclusive_group": "group2",
+                    },
+                    {
+                        "name": ["--next"],
+                        "help": "Output the next version.",
+                        "type": str,
+                        "nargs": "?",
+                        "default": None,
+                        "const": "USE_GIT_COMMITS",
+                        "choices": ["USE_GIT_COMMITS"]
+                        + [str(increment) for increment in VersionIncrement],
+                        "exclusive_group": "group2",
+                    },
+                    {
+                        "name": "manual_version",
+                        "type": str,
+                        "nargs": "?",
+                        "help": "Use the version provided instead of the version from the project. Can be used to test the selected version scheme.",
+                        "metavar": "MANUAL_VERSION",
+                    },
                 ],
             },
         ],
diff --git a/commitizen/commands/version.py b/commitizen/commands/version.py
@@ -2,21 +2,31 @@
 import sys
 from typing import TypedDict
 
+from packaging.version import InvalidVersion
+
 from commitizen import out
 from commitizen.__version__ import __version__
 from commitizen.config import BaseConfig
 from commitizen.exceptions import NoVersionSpecifiedError, VersionSchemeUnknown
 from commitizen.providers import get_provider
+from commitizen.version_increment import VersionIncrement
 from commitizen.version_schemes import get_version_scheme
 
 
 class VersionArgs(TypedDict, total=False):
+    manual_version: str | None
+    next: str | None
+
+    # Exclusive groups 1
     commitizen: bool
     report: bool
     project: bool
     verbose: bool
+
+    # Exclusive groups 2
     major: bool
     minor: bool
+    patch: bool
 
 
 class Version:
@@ -41,24 +51,53 @@ def __call__(self) -> None:
         if self.arguments.get("verbose"):
             out.write(f"Installed Commitizen Version: {__version__}")
 
-        if not self.arguments.get("commitizen") and (
-            self.arguments.get("project") or self.arguments.get("verbose")
+        if self.arguments.get("commitizen"):
+            out.write(__version__)
+            return
+
+        if (
+            self.arguments.get("project")
+            or self.arguments.get("verbose")
+            or self.arguments.get("next")
+            or self.arguments.get("manual_version")
         ):
+            version_str = self.arguments.get("manual_version")
+            if version_str is None:
+                try:
+                    version_str = get_provider(self.config).get_version()
+                except NoVersionSpecifiedError:
+                    out.error("No project information in this project.")
+                    return
             try:
-                version = get_provider(self.config).get_version()
-            except NoVersionSpecifiedError:
-                out.error("No project information in this project.")
-                return
-            try:
-                version_scheme = get_version_scheme(self.config.settings)(version)
+                version_scheme = get_version_scheme(self.config.settings)
             except VersionSchemeUnknown:
                 out.error("Unknown version scheme.")
                 return
 
+            try:
+                version = version_scheme(version_str)
+            except InvalidVersion:
+                out.error(f"Invalid version: '{version_str}'")
+                return
+
+            if next_increment_str := self.arguments.get("next"):
+                if next_increment_str == "USE_GIT_COMMITS":
+                    # TODO: implement this
+                    raise NotImplementedError("USE_GIT_COMMITS is not implemented")
+
+                next_increment = VersionIncrement.from_value(next_increment_str)
+                # TODO: modify the interface of bump to accept VersionIncrement
+                version = version.bump(increment=str(next_increment))  # type: ignore[arg-type]
+
             if self.arguments.get("major"):
-                version = f"{version_scheme.major}"
-            elif self.arguments.get("minor"):
-                version = f"{version_scheme.minor}"
+                out.write(version.major)
+                return
+            if self.arguments.get("minor"):
+                out.write(version.minor)
+                return
+            if self.arguments.get("patch"):
+                out.write(version.micro)
+                return
 
             out.write(
                 f"Project Version: {version}"
@@ -67,11 +106,12 @@ 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."
-            )
-            return
+        for argument in ("major", "minor", "patch"):
+            if self.arguments.get(argument):
+                out.error(
+                    f"{argument} can only be used with MANUAL_VERSION, --project or --verbose."
+                )
+                return
 
         # If no arguments are provided, just show the installed commitizen version
         out.write(__version__)
diff --git a/commitizen/git.py b/commitizen/git.py
@@ -21,10 +21,10 @@ class EOLType(Enum):
     def for_open(cls) -> str:
         c = cmd.run("git config core.eol")
         eol = c.out.strip().upper()
-        return cls._char_for_open()[cls._safe_cast(eol)]
+        return cls._char_for_open()[cls._from_value(eol)]
 
     @classmethod
-    def _safe_cast(cls, eol: str) -> EOLType:
+    def _from_value(cls, eol: str) -> EOLType:
         try:
             return cls[eol]
         except KeyError:
diff --git a/commitizen/out.py b/commitizen/out.py
@@ -9,35 +9,35 @@
         sys.stdout.reconfigure(encoding="utf-8")
 
 
-def write(value: str, *args: object) -> None:
+def write(value: object, *args: object) -> None:
     """Intended to be used when value is multiline."""
     print(value, *args)
 
 
-def line(value: str, *args: object, **kwargs: Any) -> None:
+def line(value: object, *args: object, **kwargs: Any) -> None:
     """Wrapper in case I want to do something different later."""
     print(value, *args, **kwargs)
 
 
-def error(value: str) -> None:
-    message = colored(value, "red")
+def error(value: object) -> None:
+    message = colored(str(value), "red")
     line(message, file=sys.stderr)
 
 
-def success(value: str) -> None:
-    message = colored(value, "green")
+def success(value: object) -> None:
+    message = colored(str(value), "green")
     line(message)
 
 
-def info(value: str) -> None:
-    message = colored(value, "blue")
+def info(value: object) -> None:
+    message = colored(str(value), "blue")
     line(message)
 
 
-def diagnostic(value: str) -> None:
+def diagnostic(value: object) -> None:
     line(value, file=sys.stderr)
 
 
-def warn(value: str) -> None:
-    message = colored(value, "magenta")
+def warn(value: object) -> None:
+    message = colored(str(value), "magenta")
     line(message, file=sys.stderr)
diff --git a/commitizen/version_increment.py b/commitizen/version_increment.py
@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class VersionIncrement(IntEnum):
+    """An enumeration representing semantic versioning increments.
+    This class defines the four types of version increments according to semantic versioning:
+    - NONE: For commits that don't require a version bump (docs, style, etc.)
+    - PATCH: For backwards-compatible bug fixes
+    - MINOR: For backwards-compatible functionality additions
+    - MAJOR: For incompatible API changes
+    """
+
+    NONE = 0
+    PATCH = 1
+    MINOR = 2
+    MAJOR = 3
+
+    def __str__(self) -> str:
+        return self.name
+
+    @classmethod
+    def from_value(cls, value: object) -> VersionIncrement:
+        if not isinstance(value, str):
+            return VersionIncrement.NONE
+        try:
+            return cls[value]
+        except KeyError:
+            return VersionIncrement.NONE
diff --git a/docs/commands/version.md b/docs/commands/version.md
@@ -3,3 +3,5 @@ Get the version of the installed Commitizen or the current project (default: ins
 ## Usage
 
 ![cz version --help](../images/cli_help/cz_version___help.svg)
+
+<!-- TODO: add documentation after this feature is stabilized -->
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_version_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_version_.txt
@@ -1,16 +1,29 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v]
+                  [--major | --minor | --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+                  [MANUAL_VERSION]
 
-get the version of the installed commitizen or the current project (default:
-installed commitizen)
+Shows version of Commitizen or the version of the current project. Combine
+with other options to simulate the version increment process and play with the
+selected version scheme. If no arguments are provided, just show the installed
+Commitizen version.
+
+positional arguments:
+  MANUAL_VERSION        Use the version provided instead of the version from
+                        the project. Can be used to test the selected version
+                        scheme.
 
 options:
-  -h, --help        show this help message and exit
-  -r, --report      get system information for reporting bugs
-  -p, --project     get the version of the current project
-  -c, --commitizen  get the version of the installed commitizen
-  -v, --verbose     get the version of both the installed commitizen and the
-                    current project
-  --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
-                    or --verbose.
+  -h, --help            show this help message and exit
+  -r, --report          Get system information for reporting bugs
+  -p, --project         Get the version of the current project
+  -c, --commitizen      Get the version of the installed commitizen
+  -v, --verbose         Get the version of both the installed commitizen and
+                        the current project
+  --major               Output the major version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --minor               Output the minor version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --patch               Output the patch version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]
+                        Output the next version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_version_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_version_.txt
@@ -1,16 +1,29 @@
-usage: cz version [-h] [-r | -p | -c | -v] [--major | --minor]
+usage: cz version [-h] [-r | -p | -c | -v]
+                  [--major | --minor | --patch | --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]]
+                  [MANUAL_VERSION]
 
-get the version of the installed commitizen or the current project (default:
-installed commitizen)
+Shows version of Commitizen or the version of the current project. Combine
+with other options to simulate the version increment process and play with the
+selected version scheme. If no arguments are provided, just show the installed
+Commitizen version.
+
+positional arguments:
+  MANUAL_VERSION        Use the version provided instead of the version from
+                        the project. Can be used to test the selected version
+                        scheme.
 
 options:
-  -h, --help        show this help message and exit
-  -r, --report      get system information for reporting bugs
-  -p, --project     get the version of the current project
-  -c, --commitizen  get the version of the installed commitizen
-  -v, --verbose     get the version of both the installed commitizen and the
-                    current project
-  --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
-                    or --verbose.
+  -h, --help            show this help message and exit
+  -r, --report          Get system information for reporting bugs
+  -p, --project         Get the version of the current project
+  -c, --commitizen      Get the version of the installed commitizen
+  -v, --verbose         Get the version of both the installed commitizen and
+                        the current project
+  --major               Output the major version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --minor               Output the minor version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --patch               Output the patch version only. Need to be used with
+                        MANUAL_VERSION, --project or --verbose.
+  --next [{USE_GIT_COMMITS,NONE,PATCH,MINOR,MAJOR}]
+                        Output the next version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_version_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_version_.txt
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_version_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_version_.txt
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_version_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_version_.txt
diff --git a/tests/commands/test_version_command.py b/tests/commands/test_version_command.py
