0
# bump-my-version
1

2
A comprehensive tool for automating version management in software projects. bump-my-version provides both CLI commands and Python API for incrementing version numbers, updating files, creating SCM commits and tags, and integrating with automated build systems.
3

4
## Package Information
5

6
- **Package Name**: bump-my-version
7
- **Package Type**: pypi
8
- **Language**: Python (3.8+)
9
- **Installation**: `pip install bump-my-version`
10

11
## Core Imports
12

13
```python
14
import bumpversion
15
from bumpversion import __version__
16
```
17

18
For CLI functionality:
19
```python
20
from bumpversion.cli import cli
21
```
22

23
For programmatic version bumping:
24
```python
25
from bumpversion.bump import do_bump, get_next_version
26
```
27

28
For configuration management:
29
```python
30
from bumpversion.config import get_configuration
31
from bumpversion.config.models import Config
32
```
33

34
## Basic Usage
35

36
### CLI Usage (Primary Interface)
37

38
```bash
39
# Install globally
40
pip install bump-my-version
41

42
# Generate a sample configuration
43
bump-my-version sample-config --destination .bumpversion.toml
44

45
# Bump version components
46
bump-my-version bump patch    # 1.0.0 -> 1.0.1
47
bump-my-version bump minor    # 1.0.1 -> 1.1.0  
48
bump-my-version bump major    # 1.1.0 -> 2.0.0
49

50
# Set specific version
51
bump-my-version bump --new-version 2.1.0
52

53
# Show current configuration and version
54
bump-my-version show current_version
55
bump-my-version show new_version --increment patch
56

57
# Visualize version bumping options
58
bump-my-version show-bump
59

60
# Replace version in files without committing
61
bump-my-version replace --new-version 2.2.0 file1.py file2.py
62
```
63

64
### Programmatic Usage
65

66
```python
67
from bumpversion.config import get_configuration
68
from bumpversion.bump import do_bump
69

70
# Load configuration from project files
71
config = get_configuration()
72

73
# Perform version bump programmatically
74
do_bump(
75
    version_part="patch",
76
    new_version=None,
77
    config=config,
78
    config_file=None,
79
    dry_run=False
80
)
81
```
82

83
## Architecture
84

85
bump-my-version follows a modular design with several key components:
86

87
- **CLI Interface**: Click-based command-line interface providing the primary user experience
88
- **Configuration System**: Pydantic-based configuration management supporting pyproject.toml, .bumpversion.toml, and legacy formats
89
- **Version Management**: Flexible version parsing, serialization, and manipulation supporting SemVer, CalVer, and custom schemes
90
- **File Operations**: Pattern-based search and replacement system for updating version strings across multiple files
91
- **SCM Integration**: Git and Mercurial support for automated commits, tagging, and repository state management
92
- **Hook System**: Pre-commit, post-commit and setup hooks for custom automation workflows
93

94
## Capabilities
95

96
### CLI Commands
97

98
Primary command-line interface providing version management functionality through interactive commands with comprehensive configuration options.
99

100
```python { .api }
101
@click.group(
102
    context_settings={"help_option_names": ["-h", "--help"]},
103
    add_help_option=True,
104
)
105
@click.version_option(version=__version__)
106
@click.pass_context
107
def cli(ctx: Context) -> None: ...
108

109
def bump(
110
    args: List[str],
111
    config_file: Optional[str],
112
    verbose: int,
113
    allow_dirty: Optional[bool],
114
    current_version: Optional[str],
115
    new_version: Optional[str],
116
    # ... additional parameters
117
) -> None: ...
118

119
def show(
120
    args: List[str], 
121
    config_file: Optional[str], 
122
    format_: str, 
123
    increment: Optional[str], 
124
    current_version: Optional[str]
125
) -> None: ...
126

127
def replace(
128
    files: List[str],
129
    config_file: Optional[str],
130
    verbose: int,
131
    allow_dirty: Optional[bool],
132
    current_version: Optional[str],
133
    new_version: Optional[str],
134
    # ... additional parameters
135
) -> None: ...
136
```
137

138
[CLI Commands](./cli-commands.md)
139

140
### Core Version Management
141

142
Programmatic API for version parsing, manipulation, and bumping operations with support for multiple versioning schemes.
143

144
```python { .api }
145
def do_bump(
146
    version_part: Optional[str],
147
    new_version: Optional[str],
148
    config: Config,
149
    config_file: Optional[Path] = None,
150
    dry_run: bool = False
151
) -> None: ...
152

153
def get_next_version(
154
    current_version: "Version",
155
    config: Config,
156
    version_part: Optional[str],
157
    new_version: Optional[str]
158
) -> "Version": ...
159

160
class Version:
161
    def __init__(
162
        self, 
163
        version_spec: VersionSpec, 
164
        components: Dict[str, VersionComponent], 
165
        original: Optional[str] = None
166
    ): ...
167
    def bump(self, component_name: str) -> "Version": ...
168
    def values(self) -> Dict[str, VersionComponent]: ...
169
```
170

171
[Core Version Management](./core-version-management.md)
172

173
### Configuration Management
174

175
Comprehensive configuration system supporting multiple file formats with validation and environment variable overrides.
176

177
```python { .api }
178
def get_configuration(
179
    config_file: Optional[str] = None,
180
    **overrides: Any
181
) -> Config: ...
182

183
class Config(BaseSettings):
184
    current_version: str
185
    parse: str
186
    serialize: List[str]
187
    search: str
188
    replace: str
189
    files: List[FileChange]
190
    # ... additional configuration fields
191

192
def find_config_file(explicit_file: Optional[str] = None) -> Optional[Path]: ...
193
```
194

195
[Configuration Management](./configuration.md)
196

197
### File Operations
198

199
Pattern-based file modification system for updating version strings across multiple files with configurable search and replace patterns.
200

201
```python { .api }
202
class ConfiguredFile:
203
    def __init__(self, file_change: FileChange, version_config: VersionConfig): ...
204
    def update_file(
205
        self,
206
        current_version: Version,
207
        new_version: Version,
208
        context: Dict,
209
        dry_run: bool = False
210
    ) -> None: ...
211

212
def modify_files(
213
    files: List[ConfiguredFile],
214
    current_version: Version,
215
    new_version: Version,
216
    context: Dict,
217
    dry_run: bool = False
218
) -> None: ...
219
```
220

221
[File Operations](./file-operations.md)
222

223
### SCM Integration  
224

225
Source control management integration supporting Git and Mercurial for automated commits, tagging, and repository state management.
226

227
```python { .api }
228
class SCMInfo:
229
    tool: Optional[str]
230
    commit_sha: Optional[str]
231
    distance_to_latest_tag: int
232
    current_version: str
233
    branch_name: Optional[str]
234
    repository_root: Path
235

236
class Git:
237
    def commit_and_tag(
238
        self,
239
        message: str,
240
        tag_name: Optional[str] = None,
241
        tag_message: Optional[str] = None
242
    ) -> None: ...
243
    def is_dirty(self) -> bool: ...
244
```
245

246
[SCM Integration](./scm-integration.md)
247

248
### Hook System
249

250
Pre-commit, post-commit, and setup hook system for extending functionality with custom automation workflows.
251

252
```python { .api }
253
def run_setup_hooks(config: Config, current_version: Version, dry_run: bool = False) -> None: ...
254
def run_pre_commit_hooks(config: Config, current_version: Version, new_version: Version, dry_run: bool = False) -> None: ...  
255
def run_post_commit_hooks(config: Config, current_version: Version, new_version: Version, dry_run: bool = False) -> None: ...
256
```
257

258
[Hook System](./hooks.md)
259

260
## Types
261

262
### Core Configuration Types
263

264
```python { .api }
265
class FileChange(BaseModel):
266
    parse: str
267
    serialize: tuple
268
    search: str
269
    replace: str
270
    regex: bool
271
    ignore_missing_version: bool
272
    ignore_missing_file: bool
273
    filename: Optional[str] = None
274
    glob: Optional[str] = None
275
    glob_exclude: Optional[tuple] = None
276
    key_path: Optional[str] = None
277
    include_bumps: Optional[tuple] = None
278
    exclude_bumps: tuple = Field(default_factory=tuple)
279

280
class VersionComponentSpec(BaseModel):
281
    values: Optional[list] = None
282
    optional_value: Optional[str] = None
283
    first_value: Union[str, int, None] = None
284
    independent: bool = False
285
    always_increment: bool = False
286
    calver_format: Optional[str] = None
287

288
class SCMConfig:
289
    commit: bool = False
290
    tag: bool = False
291
    commit_args: str = ""
292
    message: str = "Bump version: {current_version} → {new_version}"
293
    tag_name: str = "v{new_version}"
294
    tag_message: str = "Bump version: {current_version} → {new_version}"
295
```
296

297
### Version Management Types
298

299
```python { .api }
300
class VersionConfig:
301
    def __init__(
302
        self,
303
        parse: str,
304
        serialize: Tuple[str], 
305
        search: str,
306
        replace: str,
307
        part_configs: Optional[Dict[str, VersionComponentSpec]] = None
308
    ): ...
309
    def parse(self, version_string: str, raise_error: bool = False) -> Version: ...
310

311
class VersionComponent:
312
    def __init__(self, name: str, spec: VersionComponentSpec): ...
313
    def bump(self, value: str) -> str: ...
314
    def null_value(self) -> str: ...
315
```
316

317
## Exception Classes
318

319
```python { .api }
320
class BumpVersionError(Exception):
321
    """Base exception for all bump-my-version errors."""
322

323
class ConfigurationError(BumpVersionError):
324
    """Raised when configuration is missing or invalid."""
325

326
class VersionNotFoundError(BumpVersionError):
327
    """Raised when version strings are not found in files."""
328

329
class InvalidVersionPartError(BumpVersionError):
330
    """Raised when an invalid version component is specified."""
331

332
class DirtyWorkingDirectoryError(BumpVersionError):
333
    """Raised when working directory is dirty and not allowed."""
334
```