1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
# Bump Options
<!-- When adding a new option, please keep the alphabetical order. -->
## `annotated_tag`
When set to `true`, `cz bump` is equivalent to `cz bump --annotated-tag`.
```toml title="pyproject.toml"
[tool.commitizen]
annotated_tag = true
```
## `bump_message`
Template used to specify the commit message generated when bumping.
Defaults to: `bump: version $current_version → $new_version`
| Variable | Description |
| ------------------ | ----------------------------------- |
| `$current_version` | the version existing before bumping |
| `$new_version` | version generated after bumping |
```toml title="pyproject.toml"
[tool.commitizen]
bump_message = "release $current_version → $new_version [skip-ci]"
```
## `gpg_sign`
When set to `true`, `cz bump` is equivalent to `cz bump --gpg-sign`. See [`--gpg-sign`](../commands/bump.md#-gpg-sign).
```toml title="pyproject.toml"
[tool.commitizen]
gpg_sign = true
```
## `ignored_tag_formats`
- Type: `list`
- Default: `[]`
Tags matching those formats will be totally ignored and won't raise a warning.
Each entry uses the syntax as [`tag_format`](#tag_format) with the addition of `*` that will match everything (non-greedy).
## `major_version_zero`
When set to `true`, `cz bump` is equivalent to `cz bump --major-version-zero`. See [`--major-version-zero`](../commands/bump.md#-major-version-zero).
```toml title="pyproject.toml"
[tool.commitizen]
major_version_zero = true
```
## `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 uses the syntax as `tag_format`.
## `pre_bump_hooks`
A list of optional commands that will run right *after* updating [`version_files`](#version_files) and *before* actual committing and tagging the release.
Useful when you need to generate documentation based on the new version. During
execution of the script, some environment variables are available:
| Variable | Description |
| ---------------------------- | ---------------------------------------------------------- |
| `CZ_PRE_IS_INITIAL` | `True` when this is the initial release, `False` otherwise |
| `CZ_PRE_CURRENT_VERSION` | Current version, before the bump |
| `CZ_PRE_CURRENT_TAG_VERSION` | Current version tag, before the bump |
| `CZ_PRE_NEW_VERSION` | New version, after the bump |
| `CZ_PRE_NEW_TAG_VERSION` | New version tag, after the bump |
| `CZ_PRE_MESSAGE` | Commit message of the bump |
| `CZ_PRE_INCREMENT` | Whether this is a `MAJOR`, `MINOR` or `PATCH` release |
| `CZ_PRE_CHANGELOG_FILE_NAME` | Path to the changelog file, if available |
```toml title="pyproject.toml"
[tool.commitizen]
pre_bump_hooks = [
"scripts/generate_documentation.sh"
]
```
## `post_bump_hooks`
A list of optional commands that will run right *after* committing and tagging the release.
Useful when you need to send notifications about a release, or further automate deploying the
release. During execution of the script, some environment variables are available:
| Variable | Description |
| ------------------------------ | ----------------------------------------------------------- |
| `CZ_POST_WAS_INITIAL` | `True` when this was the initial release, `False` otherwise |
| `CZ_POST_PREVIOUS_VERSION` | Previous version, before the bump |
| `CZ_POST_PREVIOUS_TAG_VERSION` | Previous version tag, before the bump |
| `CZ_POST_CURRENT_VERSION` | Current version, after the bump |
| `CZ_POST_CURRENT_TAG_VERSION` | Current version tag, after the bump |
| `CZ_POST_MESSAGE` | Commit message of the bump |
| `CZ_POST_INCREMENT` | Whether this was a `MAJOR`, `MINOR` or `PATCH` release |
| `CZ_POST_CHANGELOG_FILE_NAME` | Path to the changelog file, if available |
```toml title="pyproject.toml"
[tool.commitizen]
post_bump_hooks = [
"scripts/slack_notification.sh"
]
```
## `prerelease_offset`
Offset with which to start counting prereleases.
If not specified, defaults to `0`.
```toml title="pyproject.toml"
[tool.commitizen]
prerelease_offset = 1
```
!!! note
Under some circumstances, a prerelease cannot start with `0`-for example, in embedded projects where individual characters are encoded as bytes. You can specify an offset from which to start counting.
## `tag_format`
See [`--tag-format`](../commands/bump.md#-tag-format).
## `update_changelog_on_bump`
When set to `true`, `cz bump` is equivalent to `cz bump --changelog`.
```toml title="pyproject.toml"
[tool.commitizen]
update_changelog_on_bump = true
```
## `version_files`
Identify the files or glob patterns which should be updated with the new version.
Commitizen will update its configuration file automatically when bumping,
regardless of whether the file is present or not in `version_files`.
You may specify the `version_files` in your configuration file.
```toml title="pyproject.toml"
[tool.commitizen]
version_files = [
"src/__version__.py",
]
```
It is also possible to provide a pattern for each file, separated by a colon (e.g. `file:pattern`). See the below example for more details.
```toml title="pyproject.toml"
[tool.commitizen]
version_files = [
"packages/*/pyproject.toml:version",
"setup.json:version",
]
```
!!! note "Example scenario"
We have a project with the following configuration file `pyproject.toml`:
```toml title="pyproject.toml"
[tool.commitizen]
version_files = [
"src/__version__.py",
"packages/*/pyproject.toml:version",
"setup.json:version",
]
```
For the reference `"setup.json:version"`, it means that it will look for a file `setup.json` and will only change the lines that contain the substring `"version"`.
For example, if the content of `setup.json` is:
<!-- DEPENDENCY: repeated_version_number.json -->
```json title="setup.json"
{
"name": "magictool",
"version": "1.2.3",
"dependencies": {
"lodash": "1.2.3"
}
}
```
After running `cz bump 2.0.0`, its content will be updated to:
```diff title="setup.json"
{
"name": "magictool",
- "version": "1.2.3",
+ "version": "2.0.0",
"dependencies": {
"lodash": "1.2.3"
}
}
```
!!! note
Files can be specified using relative (to the execution) paths, absolute paths, or glob patterns.
!!! note "Historical note"
This option was renamed from `files` to `version_files`.
## `version_scheme`
See [`--version-scheme`](../commands/bump.md#-version-scheme).
|
