git-version-sync

A command-line tool to synchronize semantic versions between Git tags and project configuration files.

Links: Repository · PyPI · Issues

Features

• Check version status and consistency between Git tags and project configuration
• Sync version discrepancies with flexible sync directions
• Bump versions following semantic versioning (major, minor, patch, auto)
• Push commits and tags to remote repository with optional GitHub releases
• Undo version bumps with optional remote cleanup and automatic rollback on error
• Auto-detect configuration files (pyproject.toml, package.json, Cargo.toml, and more)
• Auto-generate changelog from commit history for each version bump
• GitHub Release integration for automated release creation
• Dry-run mode to preview changes before execution
• Flexible config flag - specify config file anywhere in command
• Custom annotations for Git tags
• Force mode for bypassing version mismatches

Installation

Requirements

• Python >= 3.10
• Git

Via PyPI (Recommended)

pip install git-version-sync

Or with pipx for isolated installation:

pipx install git-version-sync

From Source

git clone https://github.com/Finsa-SC/git-version-sync.git
cd git-version-sync
pip install -e .

Supported Configuration Files

The tool automatically detects and supports multiple configuration file formats:

| Format | File Names | Projects | |--------|-----------|----------| | TOML | pyproject.toml, Cargo.toml | Python, Rust | | JSON | package.json, composer.json | Node.js, PHP | | YAML | pubspec.yaml, docker-compose.yaml | Dart, Docker | | INI/CFG | setup.cfg, *.cfg, *.ini | Python (legacy) | | XML | pom.xml, *.xml, *.xaml | Java, .NET |

Auto-detection order: pyproject.toml → Cargo.toml → package.json → setup.cfg → pubspec.yaml → pom.xml → composer.json → docker-compose.yaml

The first file found will be used. You can also specify a custom config file with the --config flag.

Usage

Global Options

• -c, --config PATH - Path to a custom configuration file (works anywhere in the command)
• -v, --version - Display version information

Check Command

Verify version consistency between Git tags and project configuration:

git-version-sync check
git-version-sync --config package.json check
git-version-sync check --config package.json

Options:

• --no-fetch - Skip fetching tags from remote repository

Sync Command

Synchronize versions when discrepancies are detected:

git-version-sync sync

Options (mutually exclusive):

• --to-git - Force config version to match the highest Git tag
• --to-config - Force Git tag to match the version in project config

Bump Command

Increment the version in configuration file and create a corresponding Git tag:

git-version-sync bump [major|minor|patch|auto]

Arguments:

• part - Version part to increment (major, minor, patch, auto). Optional - runs interactive mode if omitted.

Modes:

• Interactive (no argument) - Suggests bump type based on commit analysis and asks for confirmation
• Auto - Automatically detects version bump without confirmation
• Manual (major/minor/patch) - Explicitly specify version bump

Options:

• -f, --force - Force bump even if version mismatch occurs
• -p, --push - Automatically push commit and tag to remote
• -m, --message MESSAGE - Custom annotation message for the Git tag
• -r, --release [NOTES] - Create a GitHub release with auto-generated changelog (requires 'gh' CLI)
• -d, --draft - Save the GitHub release as a draft (requires --release)
• -n, --dry-run - Perform a dry run without making any actual changes

Note: Changelog is auto-generated from commit history between the last version and current HEAD.

Push Command

Push the active branch and Git tags to remote repository:

git-version-sync push

Arguments:

• tags - Specific tag(s) to push (e.g., v1.0.0 v1.0.1). If empty, pushes active version tag.

Options:

• -a, --all - Push all local tags to remote
• -r, --release [NOTES] - Create GitHub releases for the pushed tag(s) (requires 'gh' CLI)

Undo Command

Undo/rollback the last version bump and delete its corresponding Git tag:

git-version-sync undo

Arguments:

• target - Specific tag/version to undo (e.g., v1.6.0). Default: latest tag.

Options:

• -r, --remote - Also delete the target tag from remote repository
• -f, --force - Bypass confirmation prompts

Examples

Check current version status

$ git-version-sync check
Version is synchronized with highest local tag (v1.13.0)

Check without fetching from remote

$ git-version-sync check --no-fetch
Version is synchronized with highest local tag (v1.13.0)

Check with custom config file (flexible positioning)

$ git-version-sync --config package.json check
$ git-version-sync check --config package.json

Bump with interactive mode (no argument)

$ git-version-sync bump
Detected feature addition in recent commits
Suggested bump: minor (v1.13.0 -> v1.14.0)
Apply this version bump? [Y/n]: y
Success bump version to v1.14.0

Bump with auto-detection

$ git-version-sync bump auto
Success bump version to v1.14.0

Bump patch version explicitly

$ git-version-sync bump patch
Success bump version to v1.13.1

Bump minor version with custom message and release

$ git-version-sync bump minor -m "Add new features" -r
Success bump version to v1.14.0
Creating GitHub Release v1.14.0 with changelog...

Bump patch version with push and GitHub release

$ git-version-sync bump patch -p -r "Bug fixes and improvements"
Success bump version to v1.13.1
Pushing commit and tag to remote...
Created GitHub Release v1.13.1 with changelog

Bump major version as draft release

$ git-version-sync bump major -p -r -d
Success bump version to v2.0.0
Pushing commit and tag to remote...
Created GitHub Release v2.0.0 (draft) with changelog

Dry-run preview before bumping

$ git-version-sync bump minor -m "Release" -p --dry-run
Updated project config to v1.14.0 (DRY RUN)
Committed changes: 'bump version to v1.14.0' (DRY RUN)
Created Git tag v1.14.0 (DRY RUN)
Pushed commit and tag to remote (DRY RUN)

Success bump version to v1.14.0 (DRY RUN - no changes made)

Push to remote

$ git-version-sync push
Pushing branch and tags to remote...

Push with GitHub release

$ git-version-sync push -r
Pushing branch and tags to remote...
Creating GitHub Release v1.13.0 with changelog...

Push specific tags with release

$ git-version-sync push v1.13.0 v1.13.1 -r
Pushing specified tags to remote...
Creating GitHub Release v1.13.0 with changelog...
Creating GitHub Release v1.13.1 with changelog...

Push all local tags

$ git-version-sync push -a
Pushing all local tags to remote...

Undo latest version bump

$ git-version-sync undo
Are you sure you want to undo v1.13.1? (y/n): y
Successfully undone version bump

Undo specific version and delete from remote

$ git-version-sync undo v1.13.1 -r -f
Successfully undone v1.13.1 and deleted from remote

Display version

$ git-version-sync --version
git-version-sync 1.13.0

How It Works

Auto-detect Version Bump

When running bump without specifying major/minor/patch, the tool analyzes commit history to suggest the appropriate version increment based on conventional commits.

Auto-generate Changelog

Changelog is automatically generated from commits between the last version tag and HEAD when creating a release. Commit messages are formatted for readability in GitHub releases.

Rollback on Error

If an error occurs during version bumping (especially when pushing to remote), the tool automatically rolls back changes to prevent inconsistent state between config and git tags.

Dependencies

• packaging>=26.3 - For version parsing and comparison
• pytest>=9.1.1 - Testing framework
• pytest-mock>=3.15.1 - Mocking library for tests

License

MIT - See LICENSE file for details

Author

Finsa-SC