Skip to content

docs(exit_codes.md): move "ignoring errors" from bump doc to exit_cod… #1714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bearomorphism merged 1 commit into from
Dec 11, 2025
Merged

docs(exit_codes.md): move "ignoring errors" from bump doc to exit_cod… #1714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 1 addition & 64 deletions docs/commands/bump.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -431,7 +431,7 @@ Useful for determining the next version based on CI for non-production environme
!!! warning
The `--get-next` flag will raise a `NoneIncrementExit` if the found commits are not eligible for a version bump.

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

### `--allow-no-commit`

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

## Avoid raising errors

Some situations from Commitizen raise an exit code different from 0.
If the error code is different from 0, any CI or script running Commitizen might be interrupted.

If you have a special use case, where you don't want to raise one of these error codes, you can
tell Commitizen to not raise them.

### Recommended use case

At the moment, we've identified that the most common error code to skip is

| Error name | Exit code |
| ----------------- | --------- |
| NoneIncrementExit | 21 |

There are some situations where you don't want to get an error code when some
commits do not match your rules, you just want those commits to be skipped.

```sh
cz -nr 21 bump
```

### Easy way

Check which error code was raised by Commitizen by running in the terminal

```sh
echo $?
```

The output should be an integer like this

```sh
3
```

And then you can tell Commitizen to ignore it:

```sh
cz --no-raise 3
```

You can tell Commitizen to skip more than one if needed:

```sh
cz --no-raise 3,4,5
```

### Longer way

Check the list of [exit_codes](../exit_codes.md) and understand which one you have
to skip and why.

Remember to document somewhere this, because you'll forget.

For example if the system raises a `NoneIncrementExit` error, you look it up
on the list, and then you can use the exit code:

```sh
cz -nr 21 bump
```

[pep440]: https://www.python.org/dev/peps/pep-0440/
[semver]: https://semver.org/
[version_files]: ../config/bump.md#version_files
169 changes: 136 additions & 33 deletions docs/exit_codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,39 +1,142 @@
# Exit Codes

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.
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.

These exit codes can be found in `commitizen/exceptions.py::ExitCode`.
All exit codes are defined in [commitizen/exceptions.py](https://github.com/commitizen-tools/commitizen/blob/master/commitizen/exceptions.py).

## Exit Code Reference

| Exception | Exit Code | Description |
| --------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| ExpectedExit | 0 | Expected exit |
| DryRunExit | 0 | Exit due to passing `--dry-run` option |
| NoCommitizenFoundException | 1 | Using a cz (e.g., `cz_jira`) that cannot be found in your system |
| NotAGitProjectError | 2 | Not in a git project |
| NoCommitsFoundError | 3 | No commit found |
| NoVersionSpecifiedError | 4 | Version can not be found in configuration file |
| NoPatternMapError | 5 | bump / changelog pattern or map can not be found in configuration file |
| BumpCommitFailedError | 6 | Commit error when bumping version |
| BumpTagFailedError | 7 | Tag error when bumping version |
| NoAnswersError | 8 | No user response given |
| CommitError | 9 | git commit error |
| NoCommitBackupError | 10 | Commit back up file cannot be found |
| NothingToCommitError | 11 | Nothing in staging to be committed |
| CustomError | 12 | `CzException` raised |
| NoCommandFoundError | 13 | No command found when running Commitizen cli (e.g., `cz --debug`) |
| InvalidCommitMessageError | 14 | The commit message does not pass `cz check` |
| MissingConfigError | 15 | Configuration missed for `cz_customize` |
| NoRevisionError | 16 | No revision found |
| CurrentVersionNotFoundError | 17 | current version cannot be found in _version_files_ |
| InvalidCommandArgumentError | 18 | The argument provide to command is invalid (e.g. `cz check -commit-msg-file filename --rev-range master..`) |
| InvalidConfigurationError | 19 | An error was found in the Commitizen Configuration, such as duplicates in `change_type_order` |
| NotAllowed | 20 | `--incremental` cannot be combined with a `rev_range` |
| NoneIncrementExit | 21 | The commits found are not eligible to be bumped |
| CharacterSetDecodeError | 22 | The character encoding of the command output could not be determined |
| GitCommandError | 23 | Unexpected failure while calling a git command |
| InvalidManualVersion | 24 | Manually provided version is invalid |
| InitFailedError | 25 | Failed to initialize pre-commit |
| RunHookError | 26 | An error occurred during a hook execution |
| VersionProviderUnknown | 27 | `version_provider` setting is set to an unknown version provider identifier |
| VersionSchemeUnknown | 28 | `version_scheme` setting is set to an unknown version scheme identifier |
| ChangelogFormatUnknown | 29 | `changelog_format` setting is set to an unknown version scheme identifier or could not be guessed |
| `ExpectedExit` | 0 | Expected exit |
| `DryRunExit` | 0 | Exit due to passing `--dry-run` option |
| `NoCommitizenFoundException` | 1 | Using a cz (e.g., `cz_jira`) that cannot be found in your system |
| `NotAGitProjectError` | 2 | Not in a git project |
| `NoCommitsFoundError` | 3 | No commits found |
| `NoVersionSpecifiedError` | 4 | Version is not specified in configuration file |
| `NoPatternMapError` | 5 | bump / changelog pattern or map can not be found in configuration file |
| `BumpCommitFailedError` | 6 | Commit failed when bumping version |
| `BumpTagFailedError` | 7 | Tag failed when bumping version |
| `NoAnswersError` | 8 | No user response given |
| `CommitError` | 9 | git commit error |
| `NoCommitBackupError` | 10 | Commit backup file is not found |
| `NothingToCommitError` | 11 | Nothing in staging to be committed |
| `CustomError` | 12 | `CzException` raised |
| `NoCommandFoundError` | 13 | No command found when running Commitizen cli (e.g., `cz --debug`) |
| `InvalidCommitMessageError` | 14 | The commit message does not pass `cz check` |
| `MissingConfigError` | 15 | Configuration is missing for `cz_customize` |
| `NoRevisionError` | 16 | No revision found |
| `CurrentVersionNotFoundError`| 17 | Current version cannot be found in `version_files` |
| `InvalidCommandArgumentError`| 18 | The argument provided to the command is invalid (e.g. `cz check -commit-msg-file filename --rev-range master..`) |
| `InvalidConfigurationError` | 19 | An error was found in the Commitizen Configuration, such as duplicates in `change_type_order` |
| `NotAllowed` | 20 | Invalid combination of command line / configuration file options |
| `NoneIncrementExit` | 21 | The commits found are not eligible to be bumped |
| `CharacterSetDecodeError` | 22 | The character encoding of the command output could not be determined |
| `GitCommandError` | 23 | Unexpected failure while calling a git command |
| `InvalidManualVersion` | 24 | Manually provided version is invalid |
| `InitFailedError` | 25 | Failed to initialize pre-commit |
| `RunHookError` | 26 | An error occurred during a hook execution |
| `VersionProviderUnknown` | 27 | Unknown `version_provider` |
| `VersionSchemeUnknown` | 28 | Unknown `version_scheme` |
| `ChangelogFormatUnknown` | 29 | Unknown `changelog_format` or cannot be determined by the file extension |
| `ConfigFileNotFound` | 30 | The configuration file is not found |
| `ConfigFileIsEmpty` | 31 | The configuration file is empty |
| `CommitMessageLengthLimitExceededError`| 32 | The commit message length exceeds the given limit. |

## Ignoring Exit Codes

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.

### Using `--no-raise` Flag

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:

- **Exit code numbers**: `21`, `3`, `4`
- **Exit code names**: `NO_INCREMENT`, `NO_COMMITS_FOUND`, `NO_VERSION_SPECIFIED`
- **Mixed format**: `21,NO_COMMITS_FOUND,4`

Multiple exit codes can be specified as a comma-separated list.

### Common Use Cases

#### Ignoring No Increment Errors

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:

```sh
cz -nr 21 bump
```

Or using the exit code name:

```sh
cz -nr NO_INCREMENT bump
```

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.

#### Ignoring Multiple Exit Codes

You can ignore multiple exit codes at once:

```sh
cz --no-raise 21,3,4 bump
```

This example ignores:

- `21` (`NoneIncrementExit`) - No eligible commits for bump
- `3` (`NoCommitsFoundError`) - No commits found
- `4` (`NoVersionSpecifiedError`) - Version not specified

### Finding the Exit Code

If you encounter an error and want to ignore it, you can find the exit code in two ways:

#### Method 1: Check the Exit Code After Running

After running a Commitizen command that fails, check the exit code:

```sh
cz bump
echo $? # Prints the exit code (e.g., 21)
```

Then use that exit code with `--no-raise`:

```sh
cz -nr 21 bump
```

#### Method 2: Look Up the Exception

1. Check the error message to identify the exception type
2. Find the corresponding exit code in the table above
3. Use that exit code with `--no-raise`

For example, if you see `NoneIncrementExit` in the error, look it up in the table to find it's exit code 21, then use:

```sh
cz -nr 21 bump
```

### Best Practices

- **Document your usage**: If you use `--no-raise` in scripts or CI/CD, document why specific exit codes are ignored
- **Be specific**: Only ignore exit codes you understand and have a reason to ignore
- **Test thoroughly**: Ensure that ignoring certain exit codes doesn't mask real problems in your workflow
- **Use exit code names**: When possible, use exit code names (e.g., `NO_INCREMENT`) instead of numbers for better readability

### Example: CI/CD Pipeline

Here's an example of using `--no-raise` in a CI/CD pipeline:

```yaml
# .github/workflows/release.yml
- name: Bump version
run: |
cz -nr NO_INCREMENT bump || true
# Continue even if no version bump is needed
```

This ensures the pipeline continues even when there are no commits eligible for a version bump.