Skip to content

Commit 3cb9b2c

Browse files
bearomorphismbearomorphism
committed
docs(exit_codes.md): move "ignoring errors" from bump doc to exit_code doc
1 parent 583acf4 commit 3cb9b2c

File tree

2 files changed

+137
-97
lines changed

2 files changed

+137
-97
lines changed

‎docs/commands/bump.md‎

Lines changed: 1 addition & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -431,7 +431,7 @@ Useful for determining the next version based on CI for non-production environme
431431
!!! warning
432432
The `--get-next` flag will raise a `NoneIncrementExit` if the found commits are not eligible for a version bump.
433433

434-
For information on how to suppress this exit, see [avoid raising errors](#avoid-raising-errors).
434+
For information on how to suppress this exit, see [Ignoring Exit Codes](../exit_codes.md#ignoring-exit-codes).
435435

436436
### `--allow-no-commit`
437437

@@ -505,69 +505,6 @@ Supported variables:
505505
| `$prerelease`, `${prerelease}` | Prerelease (alpha, beta, release candidate) |
506506
| `$devrelease`, `${devrelease}` | Development release |
507507

508-
## Avoid raising errors
509-
510-
Some situations from Commitizen raise an exit code different from 0.
511-
If the error code is different from 0, any CI or script running Commitizen might be interrupted.
512-
513-
If you have a special use case, where you don't want to raise one of these error codes, you can
514-
tell Commitizen to not raise them.
515-
516-
### Recommended use case
517-
518-
At the moment, we've identified that the most common error code to skip is
519-
520-
| Error name | Exit code |
521-
| ----------------- | --------- |
522-
| NoneIncrementExit | 21 |
523-
524-
There are some situations where you don't want to get an error code when some
525-
commits do not match your rules, you just want those commits to be skipped.
526-
527-
```sh
528-
cz -nr 21 bump
529-
```
530-
531-
### Easy way
532-
533-
Check which error code was raised by Commitizen by running in the terminal
534-
535-
```sh
536-
echo $?
537-
```
538-
539-
The output should be an integer like this
540-
541-
```sh
542-
3
543-
```
544-
545-
And then you can tell Commitizen to ignore it:
546-
547-
```sh
548-
cz --no-raise 3
549-
```
550-
551-
You can tell Commitizen to skip more than one if needed:
552-
553-
```sh
554-
cz --no-raise 3,4,5
555-
```
556-
557-
### Longer way
558-
559-
Check the list of [exit_codes](../exit_codes.md) and understand which one you have
560-
to skip and why.
561-
562-
Remember to document somewhere this, because you'll forget.
563-
564-
For example if the system raises a `NoneIncrementExit` error, you look it up
565-
on the list, and then you can use the exit code:
566-
567-
```sh
568-
cz -nr 21 bump
569-
```
570-
571508
[pep440]: https://www.python.org/dev/peps/pep-0440/
572509
[semver]: https://semver.org/
573510
[version_files]: ../config/bump.md#version_files

‎docs/exit_codes.md‎

Lines changed: 136 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,142 @@
11
# Exit Codes
22

3-
Commitizen handles expected exceptions through `CommitizenException` and returns different exit codes for different situations. They could be useful if you want to ignore specific errors in your pipeline.
3+
Commitizen handles expected exceptions through `CommitizenException` and returns different exit codes for different situations. This reference is useful when you need to ignore specific errors in your CI/CD pipeline or automation scripts.
44

5-
These exit codes can be found in `commitizen/exceptions.py::ExitCode`.
5+
All exit codes are defined in [commitizen/exceptions.py](https://github.com/commitizen-tools/commitizen/blob/master/commitizen/exceptions.py).
6+
7+
## Exit Code Reference
68

79
| Exception | Exit Code | Description |
810
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
9-
| ExpectedExit | 0 | Expected exit |
10-
| DryRunExit | 0 | Exit due to passing `--dry-run` option |
11-
| NoCommitizenFoundException | 1 | Using a cz (e.g., `cz_jira`) that cannot be found in your system |
12-
| NotAGitProjectError | 2 | Not in a git project |
13-
| NoCommitsFoundError | 3 | No commit found |
14-
| NoVersionSpecifiedError | 4 | Version can not be found in configuration file |
15-
| NoPatternMapError | 5 | bump / changelog pattern or map can not be found in configuration file |
16-
| BumpCommitFailedError | 6 | Commit error when bumping version |
17-
| BumpTagFailedError | 7 | Tag error when bumping version |
18-
| NoAnswersError | 8 | No user response given |
19-
| CommitError | 9 | git commit error |
20-
| NoCommitBackupError | 10 | Commit back up file cannot be found |
21-
| NothingToCommitError | 11 | Nothing in staging to be committed |
22-
| CustomError | 12 | `CzException` raised |
23-
| NoCommandFoundError | 13 | No command found when running Commitizen cli (e.g., `cz --debug`) |
24-
| InvalidCommitMessageError | 14 | The commit message does not pass `cz check` |
25-
| MissingConfigError | 15 | Configuration missed for `cz_customize` |
26-
| NoRevisionError | 16 | No revision found |
27-
| CurrentVersionNotFoundError | 17 | current version cannot be found in _version_files_ |
28-
| InvalidCommandArgumentError | 18 | The argument provide to command is invalid (e.g. `cz check -commit-msg-file filename --rev-range master..`) |
29-
| InvalidConfigurationError | 19 | An error was found in the Commitizen Configuration, such as duplicates in `change_type_order` |
30-
| NotAllowed | 20 | `--incremental` cannot be combined with a `rev_range` |
31-
| NoneIncrementExit | 21 | The commits found are not eligible to be bumped |
32-
| CharacterSetDecodeError | 22 | The character encoding of the command output could not be determined |
33-
| GitCommandError | 23 | Unexpected failure while calling a git command |
34-
| InvalidManualVersion | 24 | Manually provided version is invalid |
35-
| InitFailedError | 25 | Failed to initialize pre-commit |
36-
| RunHookError | 26 | An error occurred during a hook execution |
37-
| VersionProviderUnknown | 27 | `version_provider` setting is set to an unknown version provider identifier |
38-
| VersionSchemeUnknown | 28 | `version_scheme` setting is set to an unknown version scheme identifier |
39-
| ChangelogFormatUnknown | 29 | `changelog_format` setting is set to an unknown version scheme identifier or could not be guessed |
11+
| `ExpectedExit` | 0 | Expected exit |
12+
| `DryRunExit` | 0 | Exit due to passing `--dry-run` option |
13+
| `NoCommitizenFoundException` | 1 | Using a cz (e.g., `cz_jira`) that cannot be found in your system |
14+
| `NotAGitProjectError` | 2 | Not in a git project |
15+
| `NoCommitsFoundError` | 3 | No commits found |
16+
| `NoVersionSpecifiedError` | 4 | Version is not specified in configuration file |
17+
| `NoPatternMapError` | 5 | bump / changelog pattern or map can not be found in configuration file |
18+
| `BumpCommitFailedError` | 6 | Commit failed when bumping version |
19+
| `BumpTagFailedError` | 7 | Tag failed when bumping version |
20+
| `NoAnswersError` | 8 | No user response given |
21+
| `CommitError` | 9 | git commit error |
22+
| `NoCommitBackupError` | 10 | Commit backup file is not found |
23+
| `NothingToCommitError` | 11 | Nothing in staging to be committed |
24+
| `CustomError` | 12 | `CzException` raised |
25+
| `NoCommandFoundError` | 13 | No command found when running Commitizen cli (e.g., `cz --debug`) |
26+
| `InvalidCommitMessageError` | 14 | The commit message does not pass `cz check` |
27+
| `MissingConfigError` | 15 | Configuration is missing for `cz_customize` |
28+
| `NoRevisionError` | 16 | No revision found |
29+
| `CurrentVersionNotFoundError`| 17 | Current version cannot be found in `version_files` |
30+
| `InvalidCommandArgumentError`| 18 | The argument provided to the command is invalid (e.g. `cz check -commit-msg-file filename --rev-range master..`) |
31+
| `InvalidConfigurationError` | 19 | An error was found in the Commitizen Configuration, such as duplicates in `change_type_order` |
32+
| `NotAllowed` | 20 | Invalid combination of command line / configuration file options |
33+
| `NoneIncrementExit` | 21 | The commits found are not eligible to be bumped |
34+
| `CharacterSetDecodeError` | 22 | The character encoding of the command output could not be determined |
35+
| `GitCommandError` | 23 | Unexpected failure while calling a git command |
36+
| `InvalidManualVersion` | 24 | Manually provided version is invalid |
37+
| `InitFailedError` | 25 | Failed to initialize pre-commit |
38+
| `RunHookError` | 26 | An error occurred during a hook execution |
39+
| `VersionProviderUnknown` | 27 | Unknown `version_provider` |
40+
| `VersionSchemeUnknown` | 28 | Unknown `version_scheme` |
41+
| `ChangelogFormatUnknown` | 29 | Unknown `changelog_format` or cannot be determined by the file extension |
42+
| `ConfigFileNotFound` | 30 | The configuration file is not found |
43+
| `ConfigFileIsEmpty` | 31 | The configuration file is empty |
44+
| `CommitMessageLengthLimitExceededError`| 32 | The commit message length exceeds the given limit. |
45+
46+
## Ignoring Exit Codes
47+
48+
In some scenarios, you may want Commitizen to continue execution even when certain errors occur. This is particularly useful in CI/CD pipelines where you want to handle specific errors gracefully.
49+
50+
### Using `--no-raise` Flag
51+
52+
The `--no-raise` (or `-nr`) flag allows you to specify exit codes that should not cause Commitizen to exit with an error. You can use either:
53+
54+
- **Exit code numbers**: `21`, `3`, `4`
55+
- **Exit code names**: `NO_INCREMENT`, `NO_COMMITS_FOUND`, `NO_VERSION_SPECIFIED`
56+
- **Mixed format**: `21,NO_COMMITS_FOUND,4`
57+
58+
Multiple exit codes can be specified as a comma-separated list.
59+
60+
### Common Use Cases
61+
62+
#### Ignoring No Increment Errors
63+
64+
The most common use case is to ignore `NoneIncrementExit` (exit code 21) when running `cz bump`. This allows the command to succeed even when no commits are eligible for a version bump:
65+
66+
```sh
67+
cz -nr 21 bump
68+
```
69+
70+
Or using the exit code name:
71+
72+
```sh
73+
cz -nr NO_INCREMENT bump
74+
```
75+
76+
This is useful in CI pipelines where you want to run `cz bump` regularly, but don't want the pipeline to fail when there are no version-worthy commits.
77+
78+
#### Ignoring Multiple Exit Codes
79+
80+
You can ignore multiple exit codes at once:
81+
82+
```sh
83+
cz --no-raise 21,3,4 bump
84+
```
85+
86+
This example ignores:
87+
88+
- `21` (`NoneIncrementExit`) - No eligible commits for bump
89+
- `3` (`NoCommitsFoundError`) - No commits found
90+
- `4` (`NoVersionSpecifiedError`) - Version not specified
91+
92+
### Finding the Exit Code
93+
94+
If you encounter an error and want to ignore it, you can find the exit code in two ways:
95+
96+
#### Method 1: Check the Exit Code After Running
97+
98+
After running a Commitizen command that fails, check the exit code:
99+
100+
```sh
101+
cz bump
102+
echo $? # Prints the exit code (e.g., 21)
103+
```
104+
105+
Then use that exit code with `--no-raise`:
106+
107+
```sh
108+
cz -nr 21 bump
109+
```
110+
111+
#### Method 2: Look Up the Exception
112+
113+
1. Check the error message to identify the exception type
114+
2. Find the corresponding exit code in the table above
115+
3. Use that exit code with `--no-raise`
116+
117+
For example, if you see `NoneIncrementExit` in the error, look it up in the table to find it's exit code 21, then use:
118+
119+
```sh
120+
cz -nr 21 bump
121+
```
122+
123+
### Best Practices
124+
125+
- **Document your usage**: If you use `--no-raise` in scripts or CI/CD, document why specific exit codes are ignored
126+
- **Be specific**: Only ignore exit codes you understand and have a reason to ignore
127+
- **Test thoroughly**: Ensure that ignoring certain exit codes doesn't mask real problems in your workflow
128+
- **Use exit code names**: When possible, use exit code names (e.g., `NO_INCREMENT`) instead of numbers for better readability
129+
130+
### Example: CI/CD Pipeline
131+
132+
Here's an example of using `--no-raise` in a CI/CD pipeline:
133+
134+
```yaml
135+
# .github/workflows/release.yml
136+
- name: Bump version
137+
run: |
138+
cz -nr NO_INCREMENT bump || true
139+
# Continue even if no version bump is needed
140+
```
141+
142+
This ensures the pipeline continues even when there are no commits eligible for a version bump.

0 commit comments

Comments
 (0)