git/commitizen
1
0
Fork 0
Code Issues Activity
commitizen/docs/config.md
Daniel Baumann 167a3f8553
Adding upstream version 4.6.0+dfsg. 
Signed-off-by: Daniel Baumann <daniel@debian.org>
2025-04-21 11:40:48 +02:00

423 lines
12 KiB
Markdown
Raw Blame History

# Configuration
## Settings
### `name`
Type: `str`
Default: `"cz_conventional_commits"`
Name of the committing rules to use
### `version`
Type: `str`
Default: `None`
Current version. Example: "0.1.2". Required if you use `version_provider = "commitizen"`.
### `version_files`
Type: `list`
Default: `[ ]`
Files were the version will be updated. A pattern to match a line, can also be specified, separated by `:` [Read more][version_files]
### `version_provider`
Type: `str`
Default: `commitizen`
Version provider used to read and write version [Read more](#version-providers)
### `version_scheme`
Type: `str`
Default: `pep440`
Select a version scheme from the following options [`pep440`, `semver`, `semver2`].
Useful for non-python projects. [Read more][version-scheme]
### `tag_format`
Type: `str`
Default: `$version`
Format for the git tag, useful for old projects, that use a convention like `"v1.2.1"`. [Read more][tag_format]
### `legacy_tag_formats`
Type: `list`
Default: `[ ]`
Legacy git tag formats, useful for old projects that changed tag format.
Tags matching those formats will be recognized as version tags and be included in the changelog.
Each entry use the the syntax as [`tag_format`](#tag_format). [Read more][tag_format]
### `ignored_tag_formats`
Type: `list`
Default: `[ ]`
Tags matching those formats will be totally ignored and won't raise a warning.
Each entry use the the syntax as [`tag_format`](#tag_format) with the addition of `*`
that will match everything (non-greedy). [Read more][tag_format]
### `update_changelog_on_bump`
Type: `bool`
Default: `false`
Create changelog when running `cz bump`
### `gpg_sign`
Type: `bool`
Default: `false`
Use gpg signed tags instead of lightweight tags.
### `annotated_tag`
Type: `bool`
Default: `false`
Use annotated tags instead of lightweight tags. [See difference][annotated-tags-vs-lightweight]
### `bump_message`
Type: `str`
Default: `None`
Create custom commit message, useful to skip ci. [Read more][bump_message]
### `retry_after_failure`
Type: `bool`
Default: `false`
Automatically retry failed commit when running `cz commit`. [Read more][retry_after_failure]
### `allow_abort`
Type: `bool`
Default: `false`
Disallow empty commit messages, useful in ci. [Read more][allow_abort]
### `allowed_prefixes`
Type: `list`
Default: `[ "Merge", "Revert", "Pull request", "fixup!", "squash!"]`
Allow some prefixes and do not try to match the regex when checking the message [Read more][allowed_prefixes]
### `changelog_file`
Type: `str`
Default: `CHANGELOG.md`
Filename of exported changelog
### `changelog_format`
Type: `str`
Default: None
Format used to parse and generate the changelog, If not specified, guessed from [`changelog_file`](#changelog_file).
### `changelog_incremental`
Type: `bool`
Default: `false`
Update changelog with the missing versions. This is good if you don't want to replace previous versions in the file. Note: when doing `cz bump --changelog` this is automatically set to `true`
### `changelog_start_rev`
Type: `str`
Default: `None`
Start from a given git rev to generate the changelog
### `changelog_merge_prerelease`
Type: `bool`
Default: `false`
Collect all changes of prerelease versions into the next non-prerelease version when creating the changelog.
### `style`
Type: `list`
see above
Style for the prompts (It will merge this value with default style.) [See More (Styling your prompts with your favorite colors)][additional-features]
### `customize`
Type: `dict`
Default: `None`
**This is only supported when config through `toml`.** Custom rules for committing and bumping. [Read more][customization]
### `use_shortcuts`
Type: `bool`
Default: `false`
If enabled, commitizen will show keyboard shortcuts when selecting from a list. Define a `key` for each of your choices to set the key. [Read more][shortcuts]
### `major_version_zero`
Type: `bool`
Default: `false`
When true, breaking changes on a `0.x` will remain as a `0.x` version. On `false`, a breaking change will bump a `0.x` version to `1.0`. [major-version-zero]
### `prerelease_offset`
Type: `int`
Default: `0`
In some circumstances, a prerelease cannot start with a 0, e.g. in an embedded project individual characters are encoded as bytes. This can be done by specifying an offset from which to start counting. [prerelease-offset]
### `pre_bump_hooks`
Type: `list[str]`
Default: `[]`
Calls the hook scripts **before** bumping version. [Read more][pre_bump_hooks]
### `post_bump_hooks`
Type: `list[str]`
Default: `[]`
Calls the hook scripts **after** bumping the version. [Read more][post_bump_hooks]
### `encoding`
Type: `str`
Default: `utf-8`
Sets the character encoding to be used when parsing commit messages. [Read more][encoding]
### `template`
Type: `str`
Default: `None` (provided by plugin)
Provide custom changelog jinja template path relative to the current working directory. [Read more][template-customization]
### `extras`
Type: `dict[str, Any]`
Default: `{}`
Provide extra variables to the changelog template. [Read more][template-customization]
## Configuration file
### pyproject.toml, .cz.toml or cz.toml
Default and recommended configuration format for a project.
For a **python** project, we recommend adding an entry to your `pyproject.toml`.
You can also create a `.cz.toml` or `cz.toml` file at the root of your project folder.
Example configuration:
```toml
[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0"
version_files = [
"src/__version__.py",
"pyproject.toml:version"
]
update_changelog_on_bump = true
style = [
["qmark", "fg:#ff9d00 bold"],
["question", "bold"],
["answer", "fg:#ff9d00 bold"],
["pointer", "fg:#ff9d00 bold"],
["highlighted", "fg:#ff9d00 bold"],
["selected", "fg:#cc5454"],
["separator", "fg:#cc5454"],
["instruction", ""],
["text", ""],
["disabled", "fg:#858585 italic"]
]
```
### .cz.json or cz.json
Commitizen has support for JSON configuration. Recommended for `NodeJS` projects.
```json
{
"commitizen": {
"name": "cz_conventional_commits",
"version": "0.1.0",
"version_files": ["src/__version__.py", "pyproject.toml:version"],
"style": [
["qmark", "fg:#ff9d00 bold"],
["question", "bold"],
["answer", "fg:#ff9d00 bold"],
["pointer", "fg:#ff9d00 bold"],
["highlighted", "fg:#ff9d00 bold"],
["selected", "fg:#cc5454"],
["separator", "fg:#cc5454"],
["instruction", ""],
["text", ""],
["disabled", "fg:#858585 italic"]
]
}
}
```
### .cz.yaml or cz.yaml
YAML configuration is supported by Commitizen. Recommended for `Go`, `ansible`, or even `helm` charts projects.
```yaml
commitizen:
name: cz_conventional_commits
version: 0.1.0
version_files:
- src/__version__.py
- pyproject.toml:version
style:
- - qmark
- fg:#ff9d00 bold
- - question
- bold
- - answer
- fg:#ff9d00 bold
- - pointer
- fg:#ff9d00 bold
- - highlighted
- fg:#ff9d00 bold
- - selected
- fg:#cc5454
- - separator
- fg:#cc5454
- - instruction
- ""
- - text
- ""
- - disabled
- fg:#858585 italic
```
## Version providers
Commitizen can read and write version from different sources.
By default, it use the `commitizen` one which is using the `version` field from the commitizen settings.
But you can use any `commitizen.provider` entrypoint as value for `version_provider`.
Commitizen provides some version providers for some well known formats:
| name | description |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `commitizen` | Default version provider: Fetch and set version in commitizen config. |
| `scm` | Fetch the version from git and does not need to set it back |
| `pep621` | Get and set version from `pyproject.toml` `project.version` field |
| `poetry` | Get and set version from `pyproject.toml` `tool.poetry.version` field |
| `uv` | Get and set version from `pyproject.toml` `project.version` field and `uv.lock` `package.version` field whose `package.name` field is the same as `pyproject.toml` `project.name` field |
| `cargo` | Get and set version from `Cargo.toml` `project.version` field |
| `npm` | Get and set version from `package.json` `version` field, `package-lock.json` `version,packages.''.version` fields if the file exists, and `npm-shrinkwrap.json` `version,packages.''.version` fields if the file exists |
| `composer` | Get and set version from `composer.json` `project.version` field |
!!! note
The `scm` provider is meant to be used with `setuptools-scm` or any packager `*-scm` plugin.
An example in your `.cz.toml` or `cz.toml` would look like this:
```toml
[tool.commitizen]
version_provider = "pep621"
```
### Custom version provider
You can add you own version provider by extending `VersionProvider` and exposing it on the `commitizen.provider` entrypoint.
Here a quick example of a `my-provider` provider reading and writing version in a `VERSION` file.
```python title="my_provider.py"
from pathlib import Path
from commitizen.providers import VersionProvider
class MyProvider(VersionProvider):
file = Path() / "VERSION"
def get_version(self) -> str:
return self.file.read_text()
def set_version(self, version: str):
self.file.write_text(version)
```
```python title="setup.py"
from setuptools import setup
setup(
name="my-commitizen-provider",
version="0.1.0",
py_modules=["my_provider"],
install_requires=["commitizen"],
entry_points={
"commitizen.provider": [
"my-provider = my_provider:MyProvider",
]
},
)
```
[version_files]: commands/bump.md#version_files
[tag_format]: commands/bump.md#tag_format
[bump_message]: commands/bump.md#bump_message
[major-version-zero]: commands/bump.md#-major-version-zero
[prerelease-offset]: commands/bump.md#-prerelease_offset
[retry_after_failure]: commands/commit.md#retry
[allow_abort]: commands/check.md#allow-abort
[version-scheme]: commands/bump.md#version-scheme
[pre_bump_hooks]: commands/bump.md#pre_bump_hooks
[post_bump_hooks]: commands/bump.md#post_bump_hooks
[allowed_prefixes]: commands/check.md#allowed-prefixes
[additional-features]: https://github.com/tmbo/questionary#additional-features
[customization]: customization.md
[shortcuts]: customization.md#shortcut-keys
[template-customization]: customization.md#customizing-the-changelog-template
[annotated-tags-vs-lightweight]: https://stackoverflow.com/a/11514139/2047185
[encoding]: tutorials/writing_commits.md#writing-commits
View git blame Copy permalink