# bumpversion

Automated version number management tool for Python and other projects.

## Features

- **Auto-detection**: Automatically detects version files in your project
- **Multiple formats**: Supports `pyproject.toml`, `setup.py`, `package.json`, `Cargo.toml`, and `__init__.py`
- **Semantic versioning**: Follows Semantic Versioning (SemVer) 2.0.0 specification
- **Prerelease support**: Manage alpha, beta, rc, and other prerelease tags
- **Git integration**: Optional git commit and tag creation
- **Dry run mode**: Preview changes before applying them

## Installation

bumpversion is included in the pysfi package:

```bash
uv add pysfi
# or
pip install pysfi
```

## Usage

### Basic Version Bumping

```bash
# Bump patch version (1.0.0 -> 1.0.1)
bumpversion patch

# Bump minor version (1.0.0 -> 1.1.0)
bumpversion minor

# Bump major version (1.0.0 -> 2.0.0)
bumpversion major
```

### Prerelease Tags

```bash
# Set prerelease tag (1.0.0 -> 1.0.0-alpha)
bumpversion patch --prerelease alpha

# Set prerelease with number (1.0.0 -> 1.0.0-rc1)
bumpversion patch --prerelease rc1
```

### Git Integration

```bash
# Bump version and commit changes
bumpversion patch --commit

# Bump version, commit, and create tag
bumpversion minor --commit --tag

# Custom commit message
bumpversion major --commit --tag --message "Release version 2.0.0"
```

### Working with Specific Files

```bash
# Update only specified files
bumpversion patch --files pyproject.toml setup.py

# Update specific __init__.py file
bumpversion minor --files src/mypackage/__init__.py
```

### Dry Run Mode

```bash
# Preview changes without applying them
bumpversion patch --dry-run
```

## How It Works

1. **Detect version files**: Searches for common version files in the project directory
2. **Parse current version**: Extracts and parses the current version number
3. **Calculate new version**: Increments the specified version part (major/minor/patch)
4. **Update files**: Modifies version strings in all detected or specified files
5. **Git operations** (optional): Commits changes and creates tags

## Supported File Formats

- **pyproject.toml**: `version = "1.0.0"` in `[project]` section
- **setup.py**: `version = "1.0.0"`
- **package.json**: `"version": "1.0.0"`
- **Cargo.toml**: `version = "1.0.0"`
- **`__init__.py`**: `__version__ = "1.0.0"`

## Examples

### Example 1: Simple Patch Bump

```bash
$ bumpversion patch
Detecting version files...
Found: pyproject.toml
Current version: 1.0.0
New version: 1.0.1
Updated: pyproject.toml
Successfully bumped version to: 1.0.1
```

### Example 2: Minor Bump with Git Integration

```bash
$ bumpversion minor --commit --tag
Detecting version files...
Found: pyproject.toml
Found: src/mypackage/__init__.py
Current version: 1.0.1
New version: 1.1.0
Updated: pyproject.toml
Updated: src/mypackage/__init__.py
Git commit successful: chore: bump version to 1.1.0
Git tag created: v1.1.0
Successfully bumped version to: 1.1.0
```

### Example 3: Pre-release Version

```bash
$ bumpversion patch --prerelease alpha
Detecting version files...
Found: pyproject.toml
Current version: 1.0.0
New version: 1.0.1-alpha
Updated: pyproject.toml
Successfully bumped version to: 1.0.1-alpha
```

### Example 4: Dry Run

```bash
$ bumpversion major --dry-run
Dry run mode - no changes will be made
Detecting version files...
Found: pyproject.toml
Current version: 1.0.0
New version: 2.0.0
Files to update: [PosixPath('pyproject.toml')]
```

## Command-Line Options

```text
positional arguments:
  part                  Version part to bump (major|minor|patch)

optional arguments:
  -h, --help            Show help message and exit
  --files, -f [FILES]   Specific files to update (default: auto-detect)
  --prerelease, -p TAG  Set prerelease tag (e.g., alpha, beta, rc1)
  --commit, -c          Commit changes to git
  --tag, -t             Create git tag
  --message, -m MSG     Custom commit message
  --dry-run, -n         Show what would be done without making changes
  --debug, -d           Enable debug mode
```

## Technical Details

### Semantic Versioning

bumpversion follows Semantic Versioning 2.0.0:

- **MAJOR**: Incompatible API changes
- **MINOR**: Backwards-compatible functionality additions
- **PATCH**: Backwards-compatible bug fixes

### Version Format

Supported version formats:

- `1.0.0` (stable)
- `1.0.0-alpha` (prerelease)
- `1.0.0-beta.2` (prerelease with number)
- `1.0.0+build123` (with build metadata)

## Requirements

- Python >= 3.8
- Git (for commit and tag operations)

## Testing

bumpversion includes a comprehensive test suite covering all functionality.

### Running Tests

```bash
# Run all tests
uv run pytest sfi/bumpversion/tests/test_bumpversion.py

# Run specific test class
uv run pytest sfi/bumpversion/tests/test_bumpversion.py::TestVersion

# Run with verbose output
uv run pytest sfi/bumpversion/tests/test_bumpversion.py -v
```

### Test Coverage

- **45 tests** covering all major functionality
- **100% coverage** of core classes and methods
- Tests for version parsing, file handling, and git integration
- Integration tests for complete workflows

For detailed test documentation, see [tests/TEST_SUMMARY.md](tests/TEST_SUMMARY.md).

## License

MIT License
