feat(commit): add --write-message-to-file option

commitizen/cli.py

@@ -62,10 +62,15 @@
                         "action": "store_true",
                         "help": "show output to stdout, no commit, no modified files",
                     },
+                    {
+                        "name": "--write-message-to-file",
+                        "metavar": "FILE_PATH",
+                        "help": "write message to file before commiting (can be combined with --dry-run)",
+                    },
                     {
                         "name": ["-s", "--signoff"],
                         "action": "store_true",
-                        "help": "Sign off the commit",
+                        "help": "sign off the commit",
                     },
                 ],
             },

commitizen/commands/commit.py

@@ -14,6 +14,7 @@
     NoAnswersError,
     NoCommitBackupError,
     NotAGitProjectError,
+    NotAllowed,
     NothingToCommitError,
 )
 from commitizen.git import smart_open
@@ -63,10 +64,18 @@ def prompt_commit_questions(self) -> str:
 
     def __call__(self):
         dry_run: bool = self.arguments.get("dry_run")
+        write_message_to_file = self.arguments.get("write_message_to_file")
 
         if git.is_staging_clean() and not dry_run:
             raise NothingToCommitError("No files added to staging!")
 
+        if write_message_to_file is not None:
+            if not isinstance(write_message_to_file, str):
+                raise NotAllowed(
+                    "Commit message file name is broken.\n"
+                    "Check the flag `--write-message-to-file` in the terminal"
+                )
+
         retry: bool = self.arguments.get("retry")
 
         if retry:
@@ -76,6 +85,10 @@ def __call__(self):
 
         out.info(f"\n{m}\n")
 
+        if write_message_to_file:
+            with smart_open(write_message_to_file, "w") as file:
+                file.write(m)
+
         if dry_run:
             raise DryRunExit()
 

docs/commit.md

@@ -6,6 +6,11 @@ In your terminal run `cz commit` or the shortcut `cz c` to generate a guided git
 
 A commit can be signed off using `cz commit --signoff` or the shortcut `cz commit -s`.
 
+You can run `cz commit --write-message-to-file COMMIT_MSG_FILE` to additionally save the
+generated message to a file. This can be combined with the `--dry-run` flag to only
+write the message to a file and not modify files and create a commit. A possible use
+case for this is to [automatically prepare a commit message](./tutorials/auto_prepare_commit_message.md).
+
 !!! note
     To maintain platform compatibility, the `commit` command disable ANSI escaping in its output.
     In particular pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).

docs/tutorials/auto_prepare_commit_message.md

@@ -0,0 +1,45 @@
+# Automatically prepare message before commit
+
+## About
+
+It can be desirable to use commitizen for all types of commits (i.e. regular, merge,
+squash) so that the complete git history adheres to the commit message convention
+without ever having to call `cz commit` manually.
+
+To automatically prepare a commit message prior to committing, you can
+use a [Git hook](prepare-commit-msg-docs):
+
+> The [prepare-commit-msg] hook is invoked by git-commit right after preparing the
+> default log message, and before the editor is started.
+
+This allows for enforcing the usage of commitizen so that whenever a commit is about to
+be created, commitizen is used for creating the commit message. Running `git commit` or
+`git commit -m "..."` for example, would trigger commitizen and use the generated commit
+message for the commit.
+
+## How to
+
+- Step 1: Create a new [`prepare-commit-msg`][prepare-commit-msg-docs] Git hook by running the following commands from the root of the Git repository:
+
+```sh
+cd .git/hooks
+touch prepare-commit-msg
+chmod +x prepare-commit-msg
+```
+
+- Step 2: Edit the newly created file and add the following content:
+
+```sh
+#!/bin/sh
+COMMIT_MSG_FILE=$1
+exec < /dev/tty && cz commit --dry-run --write-message-to-file $COMMIT_MSG_FILE || true
+```
+
+See the Git hooks documentation on [`prepare-commit-msg` hooks][prepare-commit-msg-docs] for details on how this works.
+
+[prepare-commit-msg-docs]: https://git-scm.com/docs/githooks#_prepare_commit_msg
+
+## Drawbacks
+
+If additional hooks are used (e.g. pre-commit) that prevent a commit from being created,
+the message has to be created from scratch when commiting again.

hooks/prepare-commit-msg.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+COMMIT_MSG_FILE=$1
+exec < /dev/tty && cz commit --dry-run --write-message-to-file $COMMIT_MSG_FILE || true

mkdocs.yml

@@ -43,6 +43,7 @@ nav:
   - Tutorials:
       - Writing commits: "tutorials/writing_commits.md"
       - Auto check commits: "tutorials/auto_check.md"
+      - Auto prepare commit message: "tutorials/auto_prepare_commit_message.md"
       - GitLab CI: "tutorials/gitlab_ci.md"
       - Github Actions: "tutorials/github_actions.md"
       - Jenkins pipeline: "tutorials/jenkins_pipeline.md"

tests/commands/test_commit_command.py

@@ -12,6 +12,7 @@
     NoAnswersError,
     NoCommitBackupError,
     NotAGitProjectError,
+    NotAllowed,
     NothingToCommitError,
 )
 
@@ -109,6 +110,53 @@ def test_commit_command_with_dry_run_option(config, mocker: MockFixture):
         commit_cmd()
 
 
+@pytest.mark.usefixtures("staging_is_clean")
+def test_commit_command_with_write_message_to_file_option(
+    config, tmp_path, mocker: MockFixture
+):
+    tmp_file = tmp_path / "message"
+
+    prompt_mock = mocker.patch("questionary.prompt")
+    prompt_mock.return_value = {
+        "prefix": "feat",
+        "subject": "user created",
+        "scope": "",
+        "is_breaking_change": False,
+        "body": "",
+        "footer": "",
+    }
+
+    commit_mock = mocker.patch("commitizen.git.commit")
+    commit_mock.return_value = cmd.Command("success", "", b"", b"", 0)
+    success_mock = mocker.patch("commitizen.out.success")
+
+    commands.Commit(config, {"write_message_to_file": str(tmp_file)})()
+    success_mock.assert_called_once()
+    assert tmp_file.exists()
+    assert tmp_file.read_text() == "feat: user created"
+
+
+@pytest.mark.usefixtures("staging_is_clean")
+@pytest.mark.parametrize("message_file", [True, False, 0, 1])
+def test_commit_command_with_invalid_write_message_to_file_option(
+    config, message_file, mocker: MockFixture
+):
+    prompt_mock = mocker.patch("questionary.prompt")
+    prompt_mock.return_value = {
+        "prefix": "feat",
+        "subject": "user created",
+        "scope": "",
+        "is_breaking_change": False,
+        "body": "",
+        "footer": "",
+    }
+
+    with pytest.raises(NotAllowed):
+        print(isinstance(message_file, str))
+        commit_cmd = commands.Commit(config, {"write_message_to_file": message_file})
+        commit_cmd()
+
+
 @pytest.mark.usefixtures("staging_is_clean")
 def test_commit_command_with_signoff_option(config, mocker: MockFixture):
     prompt_mock = mocker.patch("questionary.prompt")