Skip to content

Commit f04a719

Browse files
committed
docs(tutorials): add installation guide and feature overview for hooks
1 parent 5b4f944 commit f04a719

File tree

1 file changed

+26
-25
lines changed

1 file changed

+26
-25
lines changed

docs/tutorials/auto_prepare_commit_message.md

+26-25
Original file line numberDiff line numberDiff line change
@@ -4,42 +4,43 @@
44

55
It can be desirable to use commitizen for all types of commits (i.e. regular, merge,
66
squash) so that the complete git history adheres to the commit message convention
7-
without ever having to call `cz commit` manually.
7+
without ever having to call `cz commit`.
88

99
To automatically prepare a commit message prior to committing, you can
10-
use a [Git hook](prepare-commit-msg-docs):
10+
use a [prepare-commit-msg Git hook](prepare-commit-msg-docs):
1111

12-
> The [prepare-commit-msg] hook is invoked by git-commit right after preparing the
12+
> This hook is invoked by git-commit right after preparing the
1313
> default log message, and before the editor is started.
1414
15-
This allows for enforcing the usage of commitizen so that whenever a commit is about to
16-
be created, commitizen is used for creating the commit message. Running `git commit` or
17-
`git commit -m "..."` for example, would trigger commitizen and use the generated commit
18-
message for the commit.
15+
To automatically perform arbitrary cleanup steps after a succesful commit you can use a
16+
[post-commit Git hook][post-commit-docs]:
1917

20-
## How to
18+
> This hook is invoked by git-commit. It takes no parameters, and is invoked after a
19+
> commit is made.
2120
22-
- 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:
21+
A combination of these two hooks allows for enforcing the usage of commitizen so that
22+
whenever a commit is about to be created, commitizen is used for creating the commit
23+
message. Running `git commit` or `git commit -m "..."` for example, would trigger
24+
commitizen and use the generated commit message for the commit.
2325

24-
```sh
25-
cd .git/hooks
26-
touch prepare-commit-msg
27-
chmod +x prepare-commit-msg
28-
```
26+
## Installation
2927

30-
- Step 2: Edit the newly created file and add the following content:
28+
Copy the hooks from [here](https://github.com/commitizen-tools/hooks) into the `.git/hooks` folder and make them
29+
executable by running the following commands from the root of your Git repository:
3130

32-
```sh
33-
#!/bin/sh
34-
COMMIT_MSG_FILE=$1
35-
exec < /dev/tty && cz commit --dry-run --write-message-to-file $COMMIT_MSG_FILE || true
31+
```bash
32+
wget -o .git/hooks/prepare-commit-msg https://github.com/commitizen-tools/hooks/prepare-commit-msg.py
33+
chmod +x .git/hooks/prepare-commit-msg
34+
wget -o .git/hooks/post-commit https://github.com/commitizen-tools/hooks/post-commit.py
35+
chmod +x .git/hooks/post-commit
3636
```
3737

38-
See the Git hooks documentation on [`prepare-commit-msg` hooks][prepare-commit-msg-docs] for details on how this works.
39-
40-
[prepare-commit-msg-docs]: https://git-scm.com/docs/githooks#_prepare_commit_msg
38+
## Features
4139

42-
## Drawbacks
40+
- Commits can be created using both `cz commit` and the regular `git commit`
41+
- The hooks automatically create a backup of the commit message that can be reused if
42+
the commit failed
43+
- The commit message backup can also be used via `cz commit --retry`
4344

44-
If additional hooks are used (e.g. pre-commit) that prevent a commit from being created,
45-
the message has to be created from scratch when commiting again.
45+
[post-commit-docs]: https://git-scm.com/docs/githooks#_post_commit
46+
[prepare-commit-msg-docs]: https://git-scm.com/docs/githooks#_prepare_commit_msg

0 commit comments

Comments
 (0)