Skip to content

Commit 4b6b3fb

Browse files
bearomorphismLee-W
authored andcommitted
docs(commit): rewrite command commit page
1 parent ceb2b7a commit 4b6b3fb

File tree

1 file changed

+44
-31
lines changed

1 file changed

+44
-31
lines changed

docs/commands/commit.md

Lines changed: 44 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,65 @@
1+
## Usage
2+
3+
![cz commit --help](../images/cli_help/cz_commit___help.svg)
4+
5+
## Overview
6+
17
![Using Commitizen cli](../images/demo.gif)
28

3-
## About
9+
The `commit` command provides an interactive way to create structured commits. Use either:
410

5-
In your terminal run `cz commit` or the shortcut `cz c` to generate a guided git commit.
11+
- `cz commit`
12+
- `cz c` (shortcut)
613

7-
You can run `cz commit --write-message-to-file COMMIT_MSG_FILE` to additionally save the
8-
generated message to a file. This can be combined with the `--dry-run` flag to only
9-
write the message to a file and not modify files and create a commit. A possible use
10-
case for this is to [automatically prepare a commit message](../tutorials/auto_prepare_commit_message.md).
14+
By default, Commitizen uses conventional commits, but you can customize the commit rules to match your project's needs. See the [customization guide](../customization.md) for details.
1115

16+
## Basic Usage
1217

13-
!!! note
14-
To maintain platform compatibility, the `commit` command disable ANSI escaping in its output.
15-
In particular pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).
18+
### Interactive Commit Creation
1619

17-
## Usage
20+
Simply run `cz commit` in your terminal to start the interactive commit creation process. The command will guide you through creating a properly formatted commit message according to your configured rules.
1821

19-
![cz commit --help](../images/cli_help/cz_commit___help.svg)
22+
### Writing Messages to File
2023

21-
### git options
24+
You can save the generated commit message to a file using:
25+
```sh
26+
cz commit --write-message-to-file COMMIT_MSG_FILE
27+
```
2228

23-
`git` command options that are not implemented by Commitizen can be use via the `--` syntax for the `commit` command.
24-
The syntax separates Commitizen arguments from `git commit` arguments by a double dash. This is the resulting syntax:
29+
This can be combined with `--dry-run` to only write the message without creating a commit. This is particularly useful for [automatically preparing commit messages](../tutorials/auto_prepare_commit_message.md).
30+
31+
## Advanced Features
32+
33+
### Git Command Options
34+
35+
You can pass any git commit options using the `--` syntax:
2536
```sh
2637
cz commit <commitizen-args> -- <git-cli-args>
2738

28-
# e.g., cz commit --dry-run -- -a -S
39+
# Examples:
40+
cz c --dry-run -- -a -S # Stage all changes and sign the commit
41+
cz c -a -- -n # Stage all changes and skip the pre-commit and commit-msg hooks
2942
```
30-
For example, using the `-S` option on `git commit` to sign a commit is now Commitizen compatible: `cz c -- -S`
3143

32-
!!! note
33-
Deprecation warning: A commit can be signed off using `cz commit --signoff` or the shortcut `cz commit -s`.
34-
This syntax is now deprecated in favor of the new `cz commit -- -s` syntax.
44+
!!! warning
45+
The `--signoff` option (or `-s`) is now recommended being used with the new syntax: `cz commit -- -s`. The old syntax `cz commit --signoff` is deprecated.
3546

3647
### Retry
3748

38-
You can use `cz commit --retry` to reuse the last commit message when the previous commit attempt failed.
39-
To automatically retry when running `cz commit`, you can set the `retry_after_failure`
40-
configuration option to `true`. Running `cz commit --no-retry` makes Commitizen ignore `retry_after_failure`, forcing
41-
a new commit message to be prompted.
49+
- Use `cz commit --retry` to reuse the last commit message after a failed commit attempt
50+
- Set `retry_after_failure: true` in your configuration to automatically retry
51+
- Use `cz commit --no-retry` to force a new commit message prompt
52+
53+
### Message Length Control
4254

43-
### Commit message length limit
55+
Control the length of your commit messages using the `-l` or `--message-length-limit` option:
56+
```sh
57+
cz commit -l 72 # Limits message length to 72 characters
58+
```
59+
60+
!!! note
61+
The length limit only applies to the first line of the commit message. For conventional commits, this means the limit applies from the type of change through the subject. The body and footer are not counted.
4462

45-
The argument `-l` (or `--message-length-limit`) followed by a positive number can limit the length of commit messages.
46-
An exception would be raised when the message length exceeds the limit.
47-
For example, `cz commit -l 72` will limit the length of commit messages to 72 characters.
48-
By default, the limit is set to 0, which means no limit on the length.
63+
## Technical Notes
4964

50-
**Note that the limit applies only to the first line of the message.**
51-
Specifically, for `ConventionalCommitsCz` the length only counts from the type of change to the subject,
52-
while the body and the footer are not counted.
65+
For platform compatibility, the `commit` command disables ANSI escaping in its output. This means pre-commit hooks coloring will be deactivated as discussed in [commitizen-tools/commitizen#417](https://github.com/commitizen-tools/commitizen/issues/417).

0 commit comments

Comments
 (0)