feat(check): Don't error on empty commit messages

Empty commit messages indicate to Git that the commit should be aborted.
Displaying an error message when the commit is already being aborted
typically only creates confusion. Add --reject-abort argument to the
check command and reject_abort config variable, both defaulting to false.
One may wish to pass --reject-abort in CI to ensure that a commit
created with git commit --allow-empty-message (e.g., by a script)
doesn't slip through. When the commit message is empty, determine the
outcome based on the reject_abort setting alone, ignoring the pattern.

Author: Kurt-von-Laven

commitizen/cli.py

@@ -240,6 +240,12 @@
                         "help": "commit message that needs to be checked",
                         "exclusive_group": "group1",
                     },
+                    {
+                        "name": ["--reject-abort"],
+                        "action": "store_true",
+                        "default": False,
+                        "help": "disallow empty commit messages, useful in ci",
+                    },
                 ],
             },
             {

commitizen/commands/check.py

@@ -26,22 +26,26 @@ def __init__(self, config: BaseConfig, arguments: Dict[str, str], cwd=os.getcwd(
         self.commit_msg_file: Optional[str] = arguments.get("commit_msg_file")
         self.commit_msg: Optional[str] = arguments.get("message")
         self.rev_range: Optional[str] = arguments.get("rev_range")
+        self.reject_abort: bool = bool(
+            arguments.get("reject_abort", config.settings["reject_abort"])
+        )
 
         self._valid_command_argument()
 
         self.config: BaseConfig = config
         self.cz = factory.commiter_factory(self.config)
 
     def _valid_command_argument(self):
-        number_args_provided = (
-            bool(self.commit_msg_file) + bool(self.commit_msg) + bool(self.rev_range)
+        num_exclusive_args_provided = sum(
+            arg is not None
+            for arg in (self.commit_msg_file, self.commit_msg, self.rev_range)
         )
-        if number_args_provided == 0 and not os.isatty(0):
+        if num_exclusive_args_provided == 0 and not os.isatty(0):
             self.commit_msg: Optional[str] = sys.stdin.read()
-        elif number_args_provided != 1:
+        elif num_exclusive_args_provided != 1:
             raise InvalidCommandArgumentError(
                 (
-                    "One and only one argument is required for check command! "
+                    "Only one of --rev-range, --message, and --commit-msg-file is permitted by check command! "
                     "See 'cz check -h' for more information"
                 )
             )
@@ -60,7 +64,7 @@ def __call__(self):
         ill_formated_commits = [
             commit
             for commit in commits
-            if not Check.validate_commit_message(commit.message, pattern)
+            if not self.validate_commit_message(commit.message, pattern)
         ]
         displayed_msgs_content = "\n".join(
             [
@@ -79,15 +83,15 @@ def __call__(self):
 
     def _get_commits(self):
         # Get commit message from file (--commit-msg-file)
-        if self.commit_msg_file:
+        if self.commit_msg_file is not None:
             with open(self.commit_msg_file, "r", encoding="utf-8") as commit_file:
                 msg = commit_file.read()
             msg = self._filter_comments(msg)
             msg = msg.lstrip("\n")
             commit_title = msg.split("\n")[0]
             commit_body = "\n".join(msg.split("\n")[1:])
             return [git.GitCommit(rev="", title=commit_title, body=commit_body)]
-        elif self.commit_msg:
+        elif self.commit_msg is not None:
             self.commit_msg = self._filter_comments(self.commit_msg)
             return [git.GitCommit(rev="", title="", body=self.commit_msg)]
 
@@ -98,8 +102,9 @@ def _filter_comments(self, msg: str) -> str:
         lines = [line for line in msg.split("\n") if not line.startswith("#")]
         return "\n".join(lines)
 
-    @staticmethod
-    def validate_commit_message(commit_msg: str, pattern: str) -> bool:
+    def validate_commit_message(self, commit_msg: str, pattern: str) -> bool:
+        if not commit_msg:
+            return not self.reject_abort
         if (
             commit_msg.startswith("Merge")
             or commit_msg.startswith("Revert")

commitizen/defaults.py

@@ -31,6 +31,7 @@ class Settings(TypedDict, total=False):
     version_files: List[str]
     tag_format: Optional[str]
     bump_message: Optional[str]
+    reject_abort: bool
     changelog_file: str
     changelog_incremental: bool
     changelog_start_rev: Optional[str]
@@ -56,6 +57,7 @@ class Settings(TypedDict, total=False):
     "version_files": [],
     "tag_format": None,  # example v$version
     "bump_message": None,  # bumped v$current_version to $new_version
+    "reject_abort": False,
     "changelog_file": "CHANGELOG.md",
     "changelog_incremental": False,
     "changelog_start_rev": None,

docs/check.md

@@ -7,7 +7,11 @@ If you want to setup an automatic check before every git commit, please refer to
 [Automatically check message before commit](auto_check.md).
 
 ## Usage
-There are three arguments that you can use one of them to check commit message.
+There are three mutually exclusive ways to use `cz check`:
+
+- with `--rev-range` to check a range of pre-existing commits
+- with `--message` or by piping the message to it to check a given string
+- or with `--commit-msg-file` to read the commit message from a file
 
 ### Git Rev Range
 If you'd like to check a commit's message after it has already been created, then you can specify the range of commits to check with `--rev-range REV_RANGE`.
@@ -46,3 +50,12 @@ $ cz check --commit-msg-file COMMIT_MSG_FILE
 
 In this option, COMMIT_MSG_FILE is the path of the temporal file that contains the commit message.
 This argument can be useful when cooperating with git hook, please check [Automatically check message before commit](auto_check.md) for more information about how to use this argument with git hook.
+
+### Reject Abort
+
+
+```bash
+cz check --message MESSAGE --reject-abort
+```
+
+Empty commit messages typically instruct Git to abort a commit, so by default they are not considered invalid. However, `git commit` accepts an `--allow-empty-message` flag (primarily for wrapper scripts), so you can use `--reject-abort` if you wish to disallow such commits (e.g., in CI). `--reject-abort` may be used in conjunction with any of the other options.

docs/config.md

@@ -131,6 +131,7 @@ commitizen:
 | `update_changelog_on_bump` | `bool` | `false`                     | Create changelog when running `cz bump`                                                                                                                                                         |
 | `annotated_tag`            | `bool` | `false`                     | Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight]                                                                                                 |
 | `bump_message`             | `str`  | `None`                      | Create custom commit message, useful to skip ci. [See more][bump_message]                                                                                                                       |
+| `reject_abort`             | `bool` | `false`                     | Disallow empty commit messages, useful in ci. [See more][reject_abort]                                                                                                                          |
 | `changelog_file`           | `str`  | `CHANGELOG.md`              | filename of exported changelog                                                                                                                                                                  |
 | `changelog_incremental`    | `bool` | `false`                     | Update changelog with the missing versions. This is good if you don't want to replace previous versions in the file. Note: when doing `cz bump --changelog` this is automatically set to `true` |
 | `changelog_start_rev`      | `str`  | `None`                      | Start from a given git rev to generate the changelog                                                                                                                                            |
@@ -141,6 +142,7 @@ commitizen:
 [version_files]: bump.md#version_files
 [tag_format]: bump.md#tag_format
 [bump_message]: bump.md#bump_message
+[reject_abort]: check.md#reject-abort
 [additional-features]: https://github.com/tmbo/questionary#additional-features
 [customization]: customization.md
 [shortcuts]: customization.md#shortcut-keys

tests/commands/test_check_command.py

@@ -206,8 +206,9 @@ def test_check_command_with_invalid_argument(config):
             config=config,
             arguments={"commit_msg_file": "some_file", "rev_range": "HEAD~10..master"},
         )
-    assert "One and only one argument is required for check command!" in str(
-        excinfo.value
+    assert (
+        "Only one of --rev-range, --message, and --commit-msg-file is permitted by check command!"
+        in str(excinfo.value)
     )
 
 
@@ -257,6 +258,46 @@ def test_check_command_with_invalid_message(config, mocker):
         error_mock.assert_called_once()
 
 
+def test_check_command_with_empty_message(config, mocker):
+    success_mock = mocker.patch("commitizen.out.success")
+    check_cmd = commands.Check(config=config, arguments={"message": ""})
+
+    check_cmd()
+    success_mock.assert_called_once()
+
+
+def test_check_command_with_reject_abort_arg(config, mocker):
+    error_mock = mocker.patch("commitizen.out.error")
+    check_cmd = commands.Check(
+        config=config, arguments={"message": "", "reject_abort": True}
+    )
+
+    with pytest.raises(InvalidCommitMessageError):
+        check_cmd()
+        error_mock.assert_called_once()
+
+
+def test_check_command_with_reject_abort_config(config, mocker):
+    error_mock = mocker.patch("commitizen.out.error")
+    config.settings["reject_abort"] = True
+    check_cmd = commands.Check(config=config, arguments={"message": ""})
+
+    with pytest.raises(InvalidCommitMessageError):
+        check_cmd()
+        error_mock.assert_called_once()
+
+
+def test_check_command_override_reject_abort_config(config, mocker):
+    success_mock = mocker.patch("commitizen.out.success")
+    config.settings["reject_abort"] = True
+    check_cmd = commands.Check(
+        config=config, arguments={"message": "", "reject_abort": False}
+    )
+
+    check_cmd()
+    success_mock.assert_called_once()
+
+
 def test_check_command_with_pipe_message(mocker, capsys):
     testargs = ["cz", "check"]
     mocker.patch.object(sys, "argv", testargs)

tests/test_conf.py

@@ -40,6 +40,7 @@
     "version": "1.0.0",
     "tag_format": None,
     "bump_message": None,
+    "reject_abort": False,
     "version_files": ["commitizen/__version__.py", "pyproject.toml"],
     "style": [["pointer", "reverse"], ["question", "underline"]],
     "changelog_file": "CHANGELOG.md",
@@ -54,6 +55,7 @@
     "version": "2.0.0",
     "tag_format": None,
     "bump_message": None,
+    "reject_abort": False,
     "version_files": ["commitizen/__version__.py", "pyproject.toml"],
     "style": [["pointer", "reverse"], ["question", "underline"]],
     "changelog_file": "CHANGELOG.md",