0
# Commitizen
1

2
A comprehensive Python release management tool designed for development teams that enforces standardized commit message conventions and automates version management workflows. Commitizen provides an interactive command-line interface for creating conventional commits, automatically bumps semantic versions based on commit history, generates and maintains changelogs, and supports extensive customization through plugins and configuration files.
3

4
## Package Information
5

6
- **Package Name**: commitizen
7
- **Language**: Python
8
- **Installation**: `pip install commitizen` or `pipx install commitizen`
9
- **Python Support**: 3.8+
10
- **Git Support**: 1.8.5.2+
11

12
## Core Imports
13

14
```python
15
# Main plugin base class
16
from commitizen import BaseCommitizen
17

18
# Configuration management
19
from commitizen.config import BaseConfig, read_cfg
20

21
# Factory for creating plugin instances
22
from commitizen.factory import commiter_factory
23

24
# Command classes for programmatic usage
25
from commitizen.commands import Bump, Check, Commit, Changelog
26

27
# Built-in plugins
28
from commitizen.cz.conventional_commits import ConventionalCommitsCz
29
from commitizen.cz.jira import JiraSmartCz
30
from commitizen.cz.customize import CustomizeCommitsCz
31

32
# Git operations
33
from commitizen import git
34

35
# Version schemes
36
from commitizen.version_schemes import get_version_scheme, Pep440, SemVer
37

38
# Output and logging utilities
39
from commitizen.out import write, line, error, success, info, diagnostic, warn
40

41
# Hook system
42
from commitizen.hooks import run
43

44
# Command execution
45
from commitizen.cmd import run, Command
46

47
# Exception handling
48
from commitizen.exceptions import CommitizenException, NoCommitizenFoundException
49
```
50

51
## Basic Usage
52

53
### CLI Installation and Setup
54

55
```bash
56
# Recommended global installation
57
pipx install commitizen
58

59
# Initialize configuration in existing project
60
cz init
61

62
# Basic workflow - interactive commit
63
git add .
64
cz commit
65

66
# Automatically bump version and generate changelog
67
cz bump --changelog
68

69
# Push changes with tags
70
git push && git push --tags
71
```
72

73
### Programmatic Usage
74

75
```python
76
from commitizen.config import BaseConfig
77
from commitizen.factory import commiter_factory
78
from commitizen.commands import bump
79

80
# Create configuration
81
config = BaseConfig()
82
config.settings.update({
83
    "name": "cz_conventional_commits",
84
    "version": "1.0.0"
85
})
86

87
# Get commitizen plugin instance  
88
cz = commiter_factory(config)
89

90
# Use plugin methods
91
questions = cz.questions()
92
example = cz.example()
93
message = cz.message({"type": "feat", "subject": "add new feature"})
94

95
# Programmatic version bumping
96
result = bump.bump(
97
    config=config,
98
    increment="MINOR", 
99
    changelog=True,
100
    dry_run=False
101
)
102
```
103

104
## Architecture
105

106
Commitizen follows a plugin-based architecture that enables customization and extensibility:
107

108
- **Core CLI**: Command-line interface built with `decli` and `argparse`
109
- **Plugin System**: Extensible commit message rules via entry points
110
- **Configuration Layer**: Multi-format config support (TOML, JSON, YAML)
111
- **Version Providers**: Support for different project types (Poetry, npm, Cargo, etc.)
112
- **Changelog Formats**: Multiple output formats (Markdown, AsciiDoc, Textile, reStructuredText)
113
- **Git Integration**: Comprehensive git operations with EOL handling and signing support
114
- **Hook System**: Pre and post-bump hooks for workflow integration
115

116
## Capabilities
117

118
### CLI Commands
119

120
Comprehensive command-line interface for interactive commit creation, version management, changelog generation, and project configuration.
121

122
```python { .api }
123
def main() -> None
124
class Bump: ...
125
class Check: ...  
126
class Commit: ...
127
class Changelog: ...
128
class Init: ...
129
class Version: ...
130
class Info: ...
131
class Example: ...
132
class Schema: ...
133
class ListCz: ...
134
```
135

136
[CLI Commands](./commands.md)
137

138
### Configuration Management
139

140
Multi-format configuration system supporting TOML, JSON, and YAML formats with comprehensive settings for version management, changelog generation, and plugin configuration.
141

142
```python { .api }
143
def read_cfg(project_root: str) -> BaseConfig
144
class BaseConfig: ...
145
class TomlConfig(BaseConfig): ...
146
class JsonConfig(BaseConfig): ...  
147
class YAMLConfig(BaseConfig): ...
148
```
149

150
[Configuration](./configuration.md)
151

152
### Plugin Development
153

154
Extensible plugin system for creating custom commit message rules, version providers, changelog formats, and version schemes.
155

156
```python { .api }
157
class BaseCommitizen: ...
158
def discover_plugins() -> None
159
def commiter_factory(config: BaseConfig) -> BaseCommitizen
160

161
# Plugin registry
162
registry: dict[str, type[BaseCommitizen]]
163
```
164

165
[Plugin Development](./plugins.md)
166

167
### Version Management
168

169
Comprehensive version management with support for semantic versioning, PEP 440, automatic file updates, and multiple version schemes.
170

171
```python { .api }
172
def find_increment(commits: list, regex: Pattern, incremental_rev: str) -> str
173
def update_version_in_files(current_version: str, new_version: str, files: list) -> None
174
def normalize_tag(tag: str, tag_format: str) -> str
175

176
class VersionProtocol: ...
177
class Pep440(BaseVersion): ...
178
class SemVer(BaseVersion): ...
179
def get_version_scheme(name: str) -> VersionProtocol
180
```
181

182
[Version Management](./version-management.md)
183

184
### Git Operations
185

186
Extensive git integration including commit creation, tag management, branch operations, repository status checking, and smart file handling with EOL support.
187

188
```python { .api }
189
def commit(message: str, args: str = "") -> Command
190
def tag(name: str, message: str = "", signed: bool = False) -> Command
191
def add(pathspecs: list[str]) -> Command
192
def get_commits(start: str = "", end: str = "", rev: str = "", paths: list[str] = []) -> list[GitCommit]
193
def get_tags() -> list[GitTag]
194
def is_git_project() -> bool
195
def find_git_project_root() -> Path
196
```
197

198
[Git Operations](./git-operations.md)
199

200
## Types
201

202
```python { .api }
203
from typing import TypedDict, Protocol, NamedTuple
204
from enum import Enum
205

206
# Configuration types
207
class CzSettings(TypedDict):
208
    bump_message: str
209
    bump_pattern: str
210
    bump_map: dict[str, str]
211
    change_type_map: dict[str, str]
212
    change_type_order: list[str]
213
    commit_parser: str
214
    message_template: str
215
    questions: list[dict]
216
    schema: str
217
    schema_pattern: str
218
    example: str
219
    info: str
220

221
class Settings(TypedDict):
222
    name: str
223
    version: str
224
    version_files: list[str]
225
    tag_format: str
226
    update_changelog_on_bump: bool
227
    changelog_file: str
228
    # ... additional settings
229

230
# Git types
231
class GitCommit(NamedTuple):
232
    rev: str
233
    title: str
234
    body: str
235
    author: str
236
    author_email: str
237
    date: str
238

239
class GitTag(NamedTuple):
240
    name: str
241
    rev: str
242
    date: str
243

244
# Version types
245
class VersionProtocol(Protocol):
246
    def parse(self, version: str) -> Any: ...
247
    def bump(self, version: Any, increment: str) -> Any: ...
248
    def serialize(self, version: Any) -> str: ...
249

250
# Exit codes
251
class ExitCode(Enum):
252
    SUCCESS = 0
253
    EXPECTED_EXIT = 21
254
    # ... 40+ additional exit codes
255

256
# Command execution
257
class Command(NamedTuple):
258
    return_code: int
259
    out: str
260
    err: str
261

262
# Output functions
263
def write(message: str, quiet: bool = False) -> None: ...
264
def line(message: str, quiet: bool = False) -> None: ...
265
def error(message: str, quiet: bool = False) -> None: ...
266
def success(message: str, quiet: bool = False) -> None: ...
267
def info(message: str, quiet: bool = False) -> None: ...
268
def diagnostic(message: str, quiet: bool = False) -> None: ...
269
def warn(message: str, quiet: bool = False) -> None: ...
270

271
# Hook execution
272
def run() -> None: ...  # Execute pre/post hooks with environment setup
273
```