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
• Undo version bumps with optional remote cleanup
• Auto-detect configuration files (pyproject.toml, package.json, Cargo.toml)
• GitHub Release integration for automated release creation
• Dry-run mode to preview changes before execution
• 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:

• pyproject.toml (Python projects)
• package.json (Node.js projects)
• Cargo.toml (Rust projects)

Detection happens in that order. The first file found will be used.

Usage

Check Command

Verify version consistency between Git tags and project configuration:

git-version-sync check

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). Default: auto (determines automatically)

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 for the bumped version (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

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

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.10.0)

Check without fetching from remote

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

Bump patch version

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

Bump with auto-detection (default)

$ git-version-sync bump
Success bump version to v1.10.1

Bump minor version with custom message

$ git-version-sync bump minor -m "Add new features"
Success bump version to v1.11.0

Bump patch version with push and GitHub release

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

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)

Dry-run preview before bumping

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

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

Push to remote

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

Push specific tags

$ git-version-sync push v1.10.0 v1.10.1
Pushing specified tags to remote...

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.10.1? (y/n): y
Successfully undone version bump

Undo specific version and delete from remote

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

Display version

$ git-version-sync --version
git-version-sync 1.10.0

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