0
# CLI Commands
1
2
Comprehensive command-line interface for interactive commit creation, version management, changelog generation, and project configuration. All commands are available through the `cz` or `git-cz` CLI tools.
3
4
## Capabilities
5
6
### Main Entry Point
7
8
The primary CLI entry point that handles argument parsing, command dispatch, and exception handling.
9
10
```python { .api }
11
def main() -> None:
12
"""
13
Main CLI entry point.
14
15
Handles command-line argument parsing, command dispatch, and exception handling.
16
Sets up logging, processes global options, and invokes the appropriate command.
17
"""
18
```
19
20
### CLI Utilities
21
22
Utility classes and functions for command-line argument parsing and exception handling.
23
24
```python { .api }
25
class ParseKwargs:
26
"""
27
Argparse action for parsing key=value arguments.
28
29
Handles quoted strings and multiple key-value pairs for CLI options.
30
"""
31
def __call__(
32
self,
33
parser: argparse.ArgumentParser,
34
namespace: argparse.Namespace,
35
kwarg: str | Sequence[Any] | None,
36
option_string: str | None = None
37
) -> None: ...
38
39
def commitizen_excepthook(
40
exc_type: type[BaseException],
41
exc_value: BaseException,
42
traceback: TracebackType | None
43
) -> None:
44
"""
45
Custom exception handler for commitizen CLI.
46
47
Provides user-friendly error messages and proper exit codes.
48
"""
49
50
def parse_no_raise(value: str) -> list[int]:
51
"""
52
Parse comma-separated exit codes without raising exceptions.
53
54
Parameters:
55
- value: Comma-separated string of exit codes
56
57
Returns:
58
List of integer exit codes
59
"""
60
```
61
62
### Version Bumping
63
64
Automatically increments project version based on commit history using semantic versioning rules, with support for changelog generation and file updates.
65
66
```python { .api }
67
class Bump:
68
"""
69
Command for automatically bumping project version based on commit history.
70
71
Supports semantic versioning, changelog generation, file updates, and hooks.
72
"""
73
def __init__(self, config: BaseConfig, arguments: dict[str, Any]):
74
"""
75
Initialize bump command.
76
77
Parameters:
78
- config: Configuration object
79
- arguments: Command arguments dictionary containing:
80
- increment: Version increment type (MAJOR, MINOR, PATCH)
81
- prerelease: Prerelease identifier (alpha, beta, rc)
82
- changelog: Generate changelog during bump
83
- changelog_to_stdout: Output changelog to stdout
84
- dry_run: Show what would be changed without making changes
85
- files_only: Only update version files, skip git operations
86
- local_version: Use local version format
87
- manual_version: Manually specify version
88
- yes: Skip confirmation prompts
89
- major_version_zero: Allow 0.x version handling
90
- retry_after_failure: Retry after failed operations
91
"""
92
93
def __call__(self) -> None:
94
"""
95
Execute version bump operation.
96
97
Raises:
98
DryRunExit: When dry_run is True
99
NotAGitProjectError: When not in a git repository
100
NoCommitsFoundError: When no commits found for increment
101
"""
102
```
103
104
### Interactive Commit Creation
105
106
Provides interactive prompts for creating standardized commit messages following configured commit conventions.
107
108
```python { .api }
109
class Commit:
110
"""
111
Command for creating commits interactively using configured rules.
112
113
Prompts user with questions defined by the active commitizen plugin.
114
"""
115
def __init__(self, config: BaseConfig, arguments: dict[str, Any]):
116
"""
117
Initialize commit command.
118
119
Parameters:
120
- config: Configuration object
121
- arguments: Command arguments dictionary containing:
122
- retry: Retry using previous commit message
123
- no_retry: Disable retry functionality
124
- dry_run: Show commit message without creating commit
125
- write_message_to_file: Write message to file instead of committing
126
- signoff: Add Signed-off-by trailer
127
- all: Automatically stage all modified files
128
- edit: Open editor for commit message
129
- message_length_limit: Maximum commit message length
130
- extra_cli_args: Additional git commit arguments
131
"""
132
133
def __call__(self) -> None:
134
"""
135
Execute interactive commit creation.
136
137
Raises:
138
DryRunExit: When dry_run is True
139
NotAGitProjectError: When not in a git repository
140
NoneIncrementExit: When no changes to commit
141
"""
142
```
143
144
### Commit Message Validation
145
146
Validates commit messages against configured rules, useful for git hooks and CI/CD pipelines.
147
148
```python { .api }
149
class Check:
150
"""
151
Command for validating commit messages against configured rules.
152
153
Can check single commits, commit ranges, or commit message files.
154
"""
155
def __init__(self, config: BaseConfig, arguments: dict[str, Any], cwd: str = None):
156
"""
157
Initialize check command.
158
159
Parameters:
160
- config: Configuration object
161
- arguments: Command arguments dictionary containing:
162
- commit_msg_file: Path to commit message file
163
- rev_range: Git revision range to check
164
- message: Direct commit message to validate
165
- allow_abort: Allow abort messages
166
- allowed_prefixes: Additional allowed commit prefixes
167
- message_length_limit: Maximum message length
168
- cwd: Working directory (optional)
169
"""
170
171
def __call__(self) -> None:
172
"""
173
Execute commit message validation.
174
175
Raises:
176
CommitMessageLengthExceededError: When message too long
177
InvalidMessageTypeError: When commit type invalid
178
"""
179
```
180
181
### Changelog Generation
182
183
Generates and maintains changelogs in various formats based on commit history and configured templates.
184
185
```python { .api }
186
class Changelog:
187
"""
188
Command for generating and maintaining project changelogs.
189
190
Supports multiple formats and incremental updates.
191
"""
192
def __init__(self, config: BaseConfig, args: dict[str, Any]):
193
"""
194
Initialize changelog command.
195
196
Parameters:
197
- config: Configuration object
198
- args: Command arguments dictionary containing:
199
- file_name: Output changelog file path
200
- incremental: Generate only new entries since last version
201
- dry_run: Output changelog to stdout without writing file
202
- start_rev: Starting revision for changelog generation
203
- rev_range: Git revision range for changelog
204
- unreleased_version: Version for unreleased changes
205
- merge_prerelease: Merge prerelease entries into final release
206
- format: Changelog format (markdown, asciidoc, textile, rst)
207
- template: Custom Jinja2 template path
208
- extras: Additional template variables
209
- version_scheme: Version scheme to use
210
- current_version: Current version override
211
- tag_format: Git tag format
212
- export_template: Export template to file
213
"""
214
215
def __call__(self) -> None:
216
"""
217
Execute changelog generation.
218
219
Raises:
220
NotAGitProjectError: When not in a git repository
221
NoCommitsFoundError: When no commits found
222
"""
223
```
224
225
### Project Initialization
226
227
Initializes commitizen configuration in existing projects with interactive setup.
228
229
```python { .api }
230
class Init:
231
"""
232
Command for initializing commitizen configuration in projects.
233
234
Creates configuration files with user-selected options.
235
"""
236
def __init__(self, config: BaseConfig, *args):
237
"""
238
Initialize init command.
239
240
Parameters:
241
- config: Configuration object
242
- args: Variable arguments (config path determined interactively)
243
"""
244
245
def __call__(self) -> None:
246
"""
247
Execute project initialization.
248
249
Prompts user for configuration options and creates config file.
250
"""
251
```
252
253
### Version Information
254
255
Displays version information for the commitizen tool and current project.
256
257
```python { .api }
258
class Version:
259
"""
260
Command for displaying version information.
261
262
Shows commitizen version and optionally project version.
263
"""
264
def __init__(self, config: BaseConfig, *args):
265
"""
266
Initialize version command.
267
268
Parameters:
269
- config: Configuration object
270
- args: Parameter dictionary containing:
271
- report: Show detailed version report
272
- project: Show project version instead of commitizen version
273
- verbose: Show additional version details
274
"""
275
276
def __call__(self) -> None:
277
"""
278
Execute version display.
279
280
Prints version information to stdout.
281
"""
282
```
283
284
### Information Display
285
286
Shows information about the currently configured commitizen plugin including rules and patterns.
287
288
```python { .api }
289
class Info:
290
"""
291
Command for displaying information about configured commitizen plugin.
292
293
Shows plugin details, rules, and configuration.
294
"""
295
def __init__(self, config: BaseConfig, *args):
296
"""
297
Initialize info command.
298
299
Parameters:
300
- config: Configuration object
301
"""
302
303
def __call__(self) -> None:
304
"""
305
Execute information display.
306
307
Prints plugin information to stdout.
308
"""
309
```
310
311
### Commit Examples
312
313
Displays example commit messages following the configured commit rules.
314
315
```python { .api }
316
class Example:
317
"""
318
Command for displaying example commit messages.
319
320
Shows examples based on configured commit rules.
321
"""
322
def __init__(self, config: BaseConfig, *args):
323
"""
324
Initialize example command.
325
326
Parameters:
327
- config: Configuration object
328
"""
329
330
def __call__(self) -> None:
331
"""
332
Execute example display.
333
334
Prints example commit messages to stdout.
335
"""
336
```
337
338
### Schema Display
339
340
Shows the commit message schema and validation patterns for the configured plugin.
341
342
```python { .api }
343
class Schema:
344
"""
345
Command for displaying commit message schema.
346
347
Shows validation patterns and structure requirements.
348
"""
349
def __init__(self, config: BaseConfig, *args):
350
"""
351
Initialize schema command.
352
353
Parameters:
354
- config: Configuration object
355
"""
356
357
def __call__(self) -> None:
358
"""
359
Execute schema display.
360
361
Prints commit message schema to stdout.
362
"""
363
```
364
365
### Plugin Listing
366
367
Lists all available commitizen plugins installed on the system.
368
369
```python { .api }
370
class ListCz:
371
"""
372
Command for listing available commitizen plugins.
373
374
Shows installed plugins and their sources.
375
"""
376
def __init__(self, config: BaseConfig, *args):
377
"""
378
Initialize list command.
379
380
Parameters:
381
- config: Configuration object
382
"""
383
384
def __call__(self) -> None:
385
"""
386
Execute plugin listing.
387
388
Prints available plugins to stdout.
389
"""
390
```
391
392
## Usage Examples
393
394
### Basic CLI Usage
395
396
```bash
397
# Interactive commit creation
398
cz commit
399
cz c # shortcut
400
401
# Version bumping with changelog
402
cz bump --changelog
403
404
# Validate commit messages
405
cz check --commit-msg-file .git/COMMIT_EDITMSG
406
cz check --rev-range origin/main..HEAD
407
408
# Generate changelog
409
cz changelog --incremental
410
cz changelog --dry-run
411
412
# Initialize configuration
413
cz init
414
415
# Show information
416
cz version --project
417
cz info
418
cz example
419
cz schema
420
cz list-cz
421
```
422
423
### Programmatic Usage
424
425
```python
426
from commitizen.commands import Bump, Check, Commit
427
from commitizen.config import BaseConfig
428
429
# Configure
430
config = BaseConfig()
431
config.set_key("name", "cz_conventional_commits")
432
config.set_key("version", "1.0.0")
433
434
# Create commit
435
commit_args = {"dry_run": True, "retry": False}
436
commit_cmd = Commit(config, commit_args)
437
commit_cmd()
438
439
# Bump version
440
bump_args = {
441
"increment": "MINOR",
442
"changelog": True,
443
"dry_run": False
444
}
445
bump_cmd = Bump(config, bump_args)
446
bump_cmd()
447
448
# Validate commits
449
check_args = {"rev_range": "origin/main..HEAD"}
450
check_cmd = Check(config, check_args)
451
check_cmd()
452
```