0
# Configuration
1
2
Multi-format configuration system supporting TOML, JSON, and YAML formats with comprehensive settings for version management, changelog generation, and plugin configuration. Commitizen automatically discovers and loads configuration from various file formats in the project root.
3
4
## Capabilities
5
6
### Configuration Loading
7
8
Automatically discovers and loads configuration from multiple file formats with priority ordering.
9
10
```python { .api }
11
def read_cfg(filepath: str | None = None) -> BaseConfig:
12
"""
13
Read configuration from file or discover automatically.
14
15
Searches for configuration in the following order when filepath is None:
16
1. pyproject.toml [tool.commitizen]
17
2. .cz.toml
18
3. .cz.json
19
4. cz.json
20
5. .cz.yaml
21
6. cz.yaml
22
7. cz.toml
23
24
Parameters:
25
- filepath: Optional path to specific configuration file
26
27
Returns:
28
BaseConfig instance with loaded settings
29
"""
30
```
31
32
### Base Configuration
33
34
Abstract base class defining the configuration interface and common functionality.
35
36
```python { .api }
37
class BaseConfig:
38
"""
39
Base configuration class providing common configuration functionality.
40
41
Handles settings management, validation, and environment variable substitution.
42
"""
43
def __init__(self):
44
"""Initialize configuration with empty settings."""
45
46
@property
47
def settings(self) -> Settings:
48
"""Get configuration settings dictionary."""
49
50
def set_key(self, key: str, value: Any) -> None:
51
"""
52
Set configuration key-value pair.
53
54
Parameters:
55
- key: Configuration key
56
- value: Configuration value
57
"""
58
59
def add_path(self, path: Path | str) -> None:
60
"""
61
Add configuration file path.
62
63
Parameters:
64
- path: Path to configuration file
65
"""
66
67
@property
68
def path(self) -> Path | None:
69
"""Get configuration file path."""
70
```
71
72
### TOML Configuration
73
74
Configuration handler for TOML format files, including pyproject.toml integration.
75
76
```python { .api }
77
class TomlConfig(BaseConfig):
78
"""
79
TOML configuration file handler.
80
81
Supports pyproject.toml [tool.commitizen] sections and standalone .cz.toml files.
82
"""
83
def __init__(self, *, data: bytes | str, path: Path | str):
84
"""
85
Initialize TOML configuration.
86
87
Parameters:
88
- data: TOML configuration data as bytes or string
89
- path: Path to TOML configuration file
90
"""
91
92
def init_empty_config_content(self) -> str:
93
"""
94
Generate empty TOML configuration template.
95
96
Returns:
97
TOML configuration template string
98
"""
99
100
def set_key(self, key: str, value: Any) -> None:
101
"""
102
Set TOML configuration key-value pair.
103
104
Parameters:
105
- key: Configuration key
106
- value: Configuration value
107
"""
108
109
@property
110
def is_empty_config(self) -> bool:
111
"""Check if TOML configuration is empty."""
112
```
113
114
### JSON Configuration
115
116
Configuration handler for JSON format files.
117
118
```python { .api }
119
class JsonConfig(BaseConfig):
120
"""
121
JSON configuration file handler.
122
123
Supports .cz.json and cz.json configuration files.
124
"""
125
def __init__(self, *, data: bytes | str, path: Path | str):
126
"""
127
Initialize JSON configuration.
128
129
Parameters:
130
- data: JSON configuration data as bytes or string
131
- path: Path to JSON configuration file
132
"""
133
134
def init_empty_config_content(self) -> str:
135
"""
136
Generate empty JSON configuration template.
137
138
Returns:
139
JSON configuration template string
140
"""
141
142
def set_key(self, key: str, value: Any) -> None:
143
"""
144
Set JSON configuration key-value pair.
145
146
Parameters:
147
- key: Configuration key
148
- value: Configuration value
149
"""
150
151
@property
152
def is_empty_config(self) -> bool:
153
"""Check if JSON configuration is empty."""
154
```
155
156
### YAML Configuration
157
158
Configuration handler for YAML format files.
159
160
```python { .api }
161
class YAMLConfig(BaseConfig):
162
"""
163
YAML configuration file handler.
164
165
Supports .cz.yaml and cz.yaml configuration files.
166
"""
167
def __init__(self, *, data: bytes | str, path: Path | str):
168
"""
169
Initialize YAML configuration.
170
171
Parameters:
172
- data: YAML configuration data as bytes or string
173
- path: Path to YAML configuration file
174
"""
175
176
def init_empty_config_content(self) -> str:
177
"""
178
Generate empty YAML configuration template.
179
180
Returns:
181
YAML configuration template string
182
"""
183
184
def set_key(self, key: str, value: Any) -> None:
185
"""
186
Set YAML configuration key-value pair.
187
188
Parameters:
189
- key: Configuration key
190
- value: Configuration value
191
"""
192
193
@property
194
def is_empty_config(self) -> bool:
195
"""Check if YAML configuration is empty."""
196
```
197
198
## Configuration Settings
199
200
### Core Settings
201
202
```python { .api }
203
class Settings(TypedDict):
204
"""Core configuration settings for commitizen."""
205
206
# Plugin and version settings
207
name: str # Plugin name (e.g., "cz_conventional_commits")
208
version: str # Current project version
209
version_files: list[str] # Files to update with new version
210
version_scheme: str # Version scheme (semver, pep440, etc.)
211
version_provider: str | None # Version provider (poetry, npm, etc.)
212
version_type: str | None # Version type override
213
214
# Tag and commit settings
215
tag_format: str # Git tag format template
216
bump_message: str # Commit message template for version bumps
217
218
# Changelog settings
219
changelog_file: str # Changelog output file path
220
changelog_format: str # Changelog format (markdown, asciidoc, etc.)
221
changelog_incremental: bool # Generate incremental changelogs
222
changelog_start_rev: str # Starting revision for changelog
223
changelog_merge_prerelease: bool # Merge prerelease entries
224
update_changelog_on_bump: bool # Auto-update changelog during bump
225
226
# Hook settings
227
pre_bump_hooks: list[str] | None # Commands to run before version bump
228
post_bump_hooks: list[str] | None # Commands to run after version bump
229
230
# Behavior settings
231
major_version_zero: bool # Handle 0.x versions specially
232
retry_after_failure: bool # Retry operations after failure
233
use_shortcuts: bool # Enable command shortcuts
234
allow_abort: bool # Allow abort commit messages
235
allowed_prefixes: list[str] # Additional allowed commit prefixes
236
prerelease_offset: int # Prerelease version offset
237
always_signoff: bool # Always add sign-off to commits
238
239
# Template and customization
240
template: str | None # Changelog template file
241
extras: dict[str, Any] # Template extra variables
242
style: list[tuple[str, str]] # Output styling configuration
243
customize: dict[str, Any] # Plugin customization settings
244
```
245
246
### Plugin-Specific Settings
247
248
```python { .api }
249
class CzSettings(TypedDict):
250
"""Plugin-specific configuration settings."""
251
252
# Message format settings
253
message_template: str # Commit message template
254
example: str # Example commit message
255
schema: str # Schema description
256
schema_pattern: str # Regex pattern for validation
257
info: str # Plugin information text
258
info_path: str | pathlib.Path # Path to info file
259
260
# Question configuration
261
questions: list[dict[str, Any]] # Interactive questions configuration
262
263
# Version bump settings
264
bump_pattern: str # Regex pattern for version increments
265
bump_map: OrderedDict[str, str] # Mapping of patterns to increment types
266
bump_map_major_version_zero: OrderedDict[str, str] # Special 0.x version mapping
267
268
# Change type settings
269
change_type_map: dict[str, str] | None # Change type to display name mapping
270
change_type_order: list[str] # Order of change types in changelog
271
272
# Parser settings
273
commit_parser: str # Commit message parser pattern
274
changelog_pattern: str # Changelog entry pattern
275
```
276
277
## Configuration Examples
278
279
### Basic pyproject.toml Configuration
280
281
```toml
282
[tool.commitizen]
283
name = "cz_conventional_commits"
284
version = "1.0.0"
285
version_files = [
286
"src/__version__.py",
287
"pyproject.toml:version"
288
]
289
tag_format = "v$version"
290
update_changelog_on_bump = true
291
```
292
293
### Advanced pyproject.toml Configuration
294
295
```toml
296
[tool.commitizen]
297
name = "cz_conventional_commits"
298
version = "2.1.0"
299
version_scheme = "semver"
300
version_provider = "poetry"
301
version_files = [
302
"src/__version__.py",
303
"pyproject.toml:version",
304
"package.json:version"
305
]
306
307
# Git settings
308
tag_format = "v$version"
309
bump_message = "release $current_version → $new_version [skip-ci]"
310
311
# Changelog settings
312
changelog_file = "CHANGELOG.md"
313
changelog_format = "markdown"
314
changelog_incremental = true
315
changelog_start_rev = "v1.0.0"
316
changelog_merge_prerelease = true
317
update_changelog_on_bump = true
318
319
# Hook settings
320
pre_bump_hooks = [
321
"scripts/run_tests.sh",
322
"scripts/update_docs.sh"
323
]
324
post_bump_hooks = [
325
"scripts/deploy.sh",
326
"scripts/notify_team.sh"
327
]
328
329
# Behavior settings
330
major_version_zero = false
331
retry_after_failure = true
332
use_shortcuts = true
333
allow_abort = false
334
always_signoff = false
335
prerelease_offset = 0
336
337
# Output styling
338
style = [
339
["question", "fg:blue bold"],
340
["answer", "fg:green"],
341
["error", "fg:red bold"]
342
]
343
```
344
345
### Custom Plugin Configuration
346
347
```toml
348
[tool.commitizen]
349
name = "cz_customize"
350
version = "1.0.0"
351
352
[tool.commitizen.customize]
353
message_template = "{{change_type}}: {{message}}"
354
example = "feature: add new authentication system"
355
schema = "<type>: <description>"
356
schema_pattern = "(feat|fix|docs|style|refactor|test|chore):\\s.*"
357
358
bump_pattern = "^(feat|fix|BREAKING)"
359
bump_map = {
360
"BREAKING" = "MAJOR",
361
"feat" = "MINOR",
362
"fix" = "PATCH"
363
}
364
365
change_type_order = ["BREAKING", "feat", "fix", "refactor", "docs"]
366
change_type_map = {
367
"feat" = "Features",
368
"fix" = "Bug Fixes",
369
"docs" = "Documentation"
370
}
371
372
[[tool.commitizen.customize.questions]]
373
type = "list"
374
name = "change_type"
375
message = "Select the type of change you are committing:"
376
choices = [
377
{value = "feat", name = "feat: A new feature"},
378
{value = "fix", name = "fix: A bug fix"},
379
{value = "docs", name = "docs: Documentation changes"}
380
]
381
382
[[tool.commitizen.customize.questions]]
383
type = "input"
384
name = "message"
385
message = "Write a short description of the change:"
386
```
387
388
### JSON Configuration Example
389
390
```json
391
{
392
"commitizen": {
393
"name": "cz_conventional_commits",
394
"version": "1.0.0",
395
"version_files": [
396
"package.json:version",
397
"src/version.js"
398
],
399
"tag_format": "v$version",
400
"update_changelog_on_bump": true,
401
"changelog_file": "CHANGELOG.md",
402
"pre_bump_hooks": [
403
"npm run test",
404
"npm run build"
405
]
406
}
407
}
408
```
409
410
### YAML Configuration Example
411
412
```yaml
413
commitizen:
414
name: cz_conventional_commits
415
version: 1.0.0
416
version_files:
417
- VERSION
418
- setup.py:version
419
tag_format: "v$version"
420
update_changelog_on_bump: true
421
changelog_file: CHANGELOG.md
422
pre_bump_hooks:
423
- make test
424
- make build
425
post_bump_hooks:
426
- make deploy
427
```
428
429
## Programmatic Usage
430
431
```python
432
from commitizen.config import BaseConfig, read_cfg
433
from pathlib import Path
434
435
# Load configuration from project
436
config = read_cfg() # Auto-discovery
437
# or
438
config = read_cfg("pyproject.toml") # Specific file
439
440
# Access settings
441
print(config.settings["name"])
442
print(config.settings["version"])
443
444
# Modify configuration
445
config.set_key("version", "2.0.0")
446
config.set_key("changelog_file", "HISTORY.md")
447
448
# Create configuration programmatically
449
custom_config = BaseConfig()
450
custom_config.set_key("name", "cz_conventional_commits")
451
custom_config.set_key("version", "1.0.0")
452
custom_config.set_key("version_files", ["setup.py:version"])
453
custom_config.set_key("tag_format", "v$version")
454
455
# Check configuration state
456
print(f"Configuration loaded from: {config.path}")
457
```