Skip to content

docs(exit-codes): general update and add docstring to exceptions.py #1662

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

Open
wants to merge 1 commit into
base: v4-10-1
Choose a base branch
from
Open

docs(exit-codes): general update and add docstring to exceptions.py #1662

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
73 changes: 70 additions & 3 deletions commitizen/exceptions.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ class ExitCode(IntEnum):
INVALID_CONFIGURATION = 19
NOT_ALLOWED = 20
NO_INCREMENT = 21
UNRECOGNIZED_CHARACTERSET_ENCODING = 22
CHARACTER_SET_DECODE_ERROR = 22
GIT_COMMAND_ERROR = 23
INVALID_MANUAL_VERSION = 24
INIT_FAILED = 25
Expand Down Expand Up @@ -72,32 +72,44 @@ def __init__(self, *args: str, **kwargs: Any) -> None:


class DryRunExit(ExpectedExit):
pass
"""Exit due to passing `--dry-run` option"""


class NoneIncrementExit(CommitizenException):
"""The commits found are not eligible to be bumped"""

exit_code = ExitCode.NO_INCREMENT


class NoCommitizenFoundException(CommitizenException):
"""Using a cz (e.g., `cz_jira`) that cannot be found in your system"""

exit_code = ExitCode.NO_COMMITIZEN_FOUND


class NotAGitProjectError(CommitizenException):
"""Not in a git project"""

exit_code = ExitCode.NOT_A_GIT_PROJECT
message = "fatal: not a git repository (or any of the parent directories): .git"


class MissingCzCustomizeConfigError(CommitizenException):
"""Configuration is missing for `cz_customize`"""

exit_code = ExitCode.MISSING_CZ_CUSTOMIZE_CONFIG
message = "fatal: customize is not set in configuration file."


class NoCommitsFoundError(CommitizenException):
"""No commits found"""

exit_code = ExitCode.NO_COMMITS_FOUND


class NoVersionSpecifiedError(CommitizenException):
"""Version is not specified in configuration file"""

exit_code = ExitCode.NO_VERSION_SPECIFIED
message = (
"[NO_VERSION_SPECIFIED]\n"
Expand All @@ -107,111 +119,166 @@ class NoVersionSpecifiedError(CommitizenException):


class NoPatternMapError(CommitizenException):
"""bump / changelog pattern or map can not be found in configuration file"""

exit_code = ExitCode.NO_PATTERN_MAP


class BumpCommitFailedError(CommitizenException):
"""Commit failed when bumping version"""

exit_code = ExitCode.BUMP_COMMIT_FAILED


class BumpTagFailedError(CommitizenException):
"""Tag failed when bumping version"""

exit_code = ExitCode.BUMP_TAG_FAILED


class CurrentVersionNotFoundError(CommitizenException):
"""current version cannot be found in _version_files_"""
Copy link
Member

@Lee-W Lee-W Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""current version cannot be found in _version_files_"""
"""Current version cannot be found in `version_files`"""


exit_code = ExitCode.CURRENT_VERSION_NOT_FOUND


class NoAnswersError(CommitizenException):
"""No user response given"""

exit_code = ExitCode.NO_ANSWERS


class CommitError(CommitizenException):
"""git commit error"""

exit_code = ExitCode.COMMIT_ERROR


class NoCommitBackupError(CommitizenException):
"""Commit backup file is not found"""

exit_code = ExitCode.NO_COMMIT_BACKUP
message = "No commit backup found"


class NothingToCommitError(CommitizenException):
"""Nothing in staging to be committed"""

exit_code = ExitCode.NOTHING_TO_COMMIT


class CustomError(CommitizenException):
"""`CzException` raised"""

exit_code = ExitCode.CUSTOM_ERROR


class InvalidCommitMessageError(CommitizenException):
"""The commit message does not pass `cz check`"""

exit_code = ExitCode.INVALID_COMMIT_MSG


class NoRevisionError(CommitizenException):
"""No revision found"""

exit_code = ExitCode.NO_REVISION
message = "No tag found to do an incremental changelog"


class NoCommandFoundError(CommitizenException):
"""No command found when running Commitizen cli (e.g., `cz --debug`)"""

exit_code = ExitCode.NO_COMMAND_FOUND
message = "Command is required"


class InvalidCommandArgumentError(CommitizenException):
"""The argument provided to the command is invalid (e.g. `cz check -commit-msg-file filename --rev-range master..`)"""

exit_code = ExitCode.INVALID_COMMAND_ARGUMENT


class InvalidConfigurationError(CommitizenException):
"""An error was found in the Commitizen Configuration, such as duplicates in `change_type_order`"""

exit_code = ExitCode.INVALID_CONFIGURATION


class NotAllowed(CommitizenException):
"""`--incremental` cannot be combined with a `rev_range`"""

exit_code = ExitCode.NOT_ALLOWED


class CharacterSetDecodeError(CommitizenException):
exit_code = ExitCode.UNRECOGNIZED_CHARACTERSET_ENCODING
"""The character encoding of the command output could not be determined"""

exit_code = ExitCode.CHARACTER_SET_DECODE_ERROR


class GitCommandError(CommitizenException):
"""Unexpected failure while calling a git command"""

exit_code = ExitCode.GIT_COMMAND_ERROR


class InvalidManualVersion(CommitizenException):
"""Manually provided version is invalid"""

exit_code = ExitCode.INVALID_MANUAL_VERSION


class InitFailedError(CommitizenException):
"""Failed to initialize pre-commit"""
Copy link
Member

@Lee-W Lee-W Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could it be other issue with cz init?


exit_code = ExitCode.INIT_FAILED


class RunHookError(CommitizenException):
"""An error occurred during a hook execution"""

exit_code = ExitCode.RUN_HOOK_FAILED


class VersionProviderUnknown(CommitizenException):
"""Unknown `version_provider`"""

exit_code = ExitCode.VERSION_PROVIDER_UNKNOWN


class VersionSchemeUnknown(CommitizenException):
"""Unknown `version_scheme`"""

exit_code = ExitCode.VERSION_SCHEME_UNKNOWN


class ChangelogFormatUnknown(CommitizenException):
"""Unknown `changelog_format` or cannot be determined by the file extension"""

exit_code = ExitCode.CHANGELOG_FORMAT_UNKNOWN
message = "Unknown changelog format identifier"


class ConfigFileNotFound(CommitizenException):
"""The configuration file is not found"""

exit_code = ExitCode.CONFIG_FILE_NOT_FOUND
message = "Cannot found the config file, please check your file path again."


class ConfigFileIsEmpty(CommitizenException):
"""The configuration file is empty"""

exit_code = ExitCode.CONFIG_FILE_IS_EMPTY
message = "Config file is empty, please check your file path again."


class CommitMessageLengthExceededError(CommitizenException):
"""The commit message length exceeds the given limit."""

exit_code = ExitCode.COMMIT_MESSAGE_LENGTH_LIMIT_EXCEEDED
message = "Length of commit message exceeds the given limit."


# When adding a new exit code, please update the documentation of the exit codes in docs/exit_codes.md
71 changes: 38 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,44 @@
# 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.

These exit codes can be found in `commitizen/exceptions.py::ExitCode`.
The following information may come in handy if you want to ignore specific errors in your pipeline.

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

| 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 | `--incremental` cannot be combined with a `rev_range` |
Copy link
Member

@Lee-W Lee-W Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it the only case?

Copy link
Contributor Author

@bearomorphism bearomorphism Nov 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. I can update the description like "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. |