CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-bump-my-version

Version-bump your software with a single command

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

bump-my-version

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.

Package Information

  • Package Name: bump-my-version
  • Package Type: pypi
  • Language: Python (3.8+)
  • Installation: pip install bump-my-version

Core Imports

import bumpversion
from bumpversion import __version__

For CLI functionality:

from bumpversion.cli import cli

For programmatic version bumping:

from bumpversion.bump import do_bump, get_next_version

For configuration management:

from bumpversion.config import get_configuration
from bumpversion.config.models import Config

Basic Usage

CLI Usage (Primary Interface)

# Install globally
pip install bump-my-version

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

# Bump version components
bump-my-version bump patch    # 1.0.0 -> 1.0.1
bump-my-version bump minor    # 1.0.1 -> 1.1.0  
bump-my-version bump major    # 1.1.0 -> 2.0.0

# Set specific version
bump-my-version bump --new-version 2.1.0

# Show current configuration and version
bump-my-version show current_version
bump-my-version show new_version --increment patch

# Visualize version bumping options
bump-my-version show-bump

# Replace version in files without committing
bump-my-version replace --new-version 2.2.0 file1.py file2.py

Programmatic Usage

from bumpversion.config import get_configuration
from bumpversion.bump import do_bump

# Load configuration from project files
config = get_configuration()

# Perform version bump programmatically
do_bump(
    version_part="patch",
    new_version=None,
    config=config,
    config_file=None,
    dry_run=False
)

Architecture

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

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

Capabilities

CLI Commands

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

@click.group(
    context_settings={"help_option_names": ["-h", "--help"]},
    add_help_option=True,
)
@click.version_option(version=__version__)
@click.pass_context
def cli(ctx: Context) -> None: ...

def bump(
    args: List[str],
    config_file: Optional[str],
    verbose: int,
    allow_dirty: Optional[bool],
    current_version: Optional[str],
    new_version: Optional[str],
    # ... additional parameters
) -> None: ...

def show(
    args: List[str], 
    config_file: Optional[str], 
    format_: str, 
    increment: Optional[str], 
    current_version: Optional[str]
) -> None: ...

def replace(
    files: List[str],
    config_file: Optional[str],
    verbose: int,
    allow_dirty: Optional[bool],
    current_version: Optional[str],
    new_version: Optional[str],
    # ... additional parameters
) -> None: ...

CLI Commands

Core Version Management

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

def do_bump(
    version_part: Optional[str],
    new_version: Optional[str],
    config: Config,
    config_file: Optional[Path] = None,
    dry_run: bool = False
) -> None: ...

def get_next_version(
    current_version: "Version",
    config: Config,
    version_part: Optional[str],
    new_version: Optional[str]
) -> "Version": ...

class Version:
    def __init__(
        self, 
        version_spec: VersionSpec, 
        components: Dict[str, VersionComponent], 
        original: Optional[str] = None
    ): ...
    def bump(self, component_name: str) -> "Version": ...
    def values(self) -> Dict[str, VersionComponent]: ...

Core Version Management

Configuration Management

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

def get_configuration(
    config_file: Optional[str] = None,
    **overrides: Any
) -> Config: ...

class Config(BaseSettings):
    current_version: str
    parse: str
    serialize: List[str]
    search: str
    replace: str
    files: List[FileChange]
    # ... additional configuration fields

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

Configuration Management

File Operations

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

class ConfiguredFile:
    def __init__(self, file_change: FileChange, version_config: VersionConfig): ...
    def update_file(
        self,
        current_version: Version,
        new_version: Version,
        context: Dict,
        dry_run: bool = False
    ) -> None: ...

def modify_files(
    files: List[ConfiguredFile],
    current_version: Version,
    new_version: Version,
    context: Dict,
    dry_run: bool = False
) -> None: ...

File Operations

SCM Integration

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

class SCMInfo:
    tool: Optional[str]
    commit_sha: Optional[str]
    distance_to_latest_tag: int
    current_version: str
    branch_name: Optional[str]
    repository_root: Path

class Git:
    def commit_and_tag(
        self,
        message: str,
        tag_name: Optional[str] = None,
        tag_message: Optional[str] = None
    ) -> None: ...
    def is_dirty(self) -> bool: ...

SCM Integration

Hook System

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

def run_setup_hooks(config: Config, current_version: Version, dry_run: bool = False) -> None: ...
def run_pre_commit_hooks(config: Config, current_version: Version, new_version: Version, dry_run: bool = False) -> None: ...  
def run_post_commit_hooks(config: Config, current_version: Version, new_version: Version, dry_run: bool = False) -> None: ...

Hook System

Types

Core Configuration Types

class FileChange(BaseModel):
    parse: str
    serialize: tuple
    search: str
    replace: str
    regex: bool
    ignore_missing_version: bool
    ignore_missing_file: bool
    filename: Optional[str] = None
    glob: Optional[str] = None
    glob_exclude: Optional[tuple] = None
    key_path: Optional[str] = None
    include_bumps: Optional[tuple] = None
    exclude_bumps: tuple = Field(default_factory=tuple)

class VersionComponentSpec(BaseModel):
    values: Optional[list] = None
    optional_value: Optional[str] = None
    first_value: Union[str, int, None] = None
    independent: bool = False
    always_increment: bool = False
    calver_format: Optional[str] = None

class SCMConfig:
    commit: bool = False
    tag: bool = False
    commit_args: str = ""
    message: str = "Bump version: {current_version} → {new_version}"
    tag_name: str = "v{new_version}"
    tag_message: str = "Bump version: {current_version} → {new_version}"

Version Management Types

class VersionConfig:
    def __init__(
        self,
        parse: str,
        serialize: Tuple[str], 
        search: str,
        replace: str,
        part_configs: Optional[Dict[str, VersionComponentSpec]] = None
    ): ...
    def parse(self, version_string: str, raise_error: bool = False) -> Version: ...

class VersionComponent:
    def __init__(self, name: str, spec: VersionComponentSpec): ...
    def bump(self, value: str) -> str: ...
    def null_value(self) -> str: ...

Exception Classes

class BumpVersionError(Exception):
    """Base exception for all bump-my-version errors."""

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

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

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

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

docs

cli-commands.md

configuration.md

core-version-management.md

file-operations.md

hooks.md

index.md

scm-integration.md

tile.json