gitbump

git-bump

Easily tag new versions with git using configurable versioning conventions.

Features

• Multiple Versioning Conventions: Support for semantic versioning (semver) and calendar versioning (calver)
• Configurable: Use .gitbump.toml configuration files for project-specific settings
• Flexible Prefixes: Customize version prefixes (v, release, etc.)
• Auto-increment: Intelligent version incrementing based on convention type
• Git Integration: Seamless git tag creation and management

Install CLI

Using go:

go install git.sr.ht/~timharek/git-bump/cmd/git-bump@latest

Using Homebrew

brew tap timharek/tap
brew install git-bump

Adding more methods in the future. Help is wanted to achieve the best coverage.

Using pre-compiled binary

Select the version you want to install [available releases] and download it and add it to your bin or something similar.

Example:

wget https://git.sr.ht/~timharek/git-bump/refs/download/<release>/git-bump-<version>-linux-amd64.tar.gz
tar xf git-bump-<version>-linux-amd64.tar.gz
cd git-bump-<version>
cp git-bump /usr/local/bin

Configuration

Initialize a configuration file in your git repository:

git bump init

This creates a .gitbump.toml file with default settings:

[versioning]
convention = 'semver'
prefix = 'v'
format = '{major}.{minor}.{patch}'
timezone = 'UTC'

[git]
remote = 'origin'
auto_push = false

[messages]
use_shortlog = false
custom_messages = []

Versioning Conventions

Semantic Versioning (semver)

• Convention: semver
• Format: {major}.{minor}.{patch}
• Increment types: major, minor, patch
• Example: v1.2.3

Calendar Versioning (calver)

• Convention: calver
• Formats:
  • YYYY.MM.DD (date-based)
  • YY.MM.DD (short year)
  • YYYY.MM.MICRO (with micro increments)
  • YY.MM.MICRO (short year with micro)
• Increment types: date, micro
• Examples: release2025.07.11, v25.07.15

Configuration Hierarchy

git-bump searches for configuration files in this order:

1. .gitbump.toml in git repository root
2. ~/.config/git-bump/config.toml
3. ~/.gitbump.toml

Usage

# Get help
git bump -h

# Bump version (uses convention-specific default increment)
git bump
# Output: v0.0.1 (semver) or release2025.07.11 (calver)

# Bump version and include shortlog between current commit and previous tag
git bump --shortlog

# Bump version with message(s)
git bump --message "Feat 1" --message "Fix 2"

# Bump specific component (semver)
git bump --minor   # v0.1.0
git bump --major   # v1.0.0
git bump --patch   # v0.0.1

# Show latest version
git bump latest

# List all version tags
git bump list

# Undo (delete) latest tag
git bump undo

# Undo (delete) tag from remote origin
git bump undo --remote origin

# Push tag to remote
git bump push

Convention-Specific Behavior

Semantic Versioning:

• Bumping minor resets patch to 0
• Bumping major resets minor and patch to 0
• Default increment: patch

Calendar Versioning:

• Date format: Updates to current date
• Micro format: Increments micro number for same month, resets to 1 for new month
• Default increment: date (for YYYY.MM.DD) or micro (for YYYY.MM.MICRO)

Examples

Semver Project

git bump init
# Edit .gitbump.toml: convention = 'semver', prefix = 'v'
git bump          # v0.0.1
git bump --minor  # v0.1.0
git bump --major  # v1.0.0

Calver Project

git bump init
# Edit .gitbump.toml: convention = 'calver', prefix = 'release', format = 'YYYY.MM.DD'
git bump  # release2025.07.11
git bump  # release2025.07.11 (same day, increments to current date)

Calver with Micro Increments

# Edit .gitbump.toml: convention = 'calver', format = 'YYYY.MM.MICRO'
git bump  # v2025.07.1
git bump  # v2025.07.2 (same month, increments micro)

Things to know

• --help will not work when running in git bump, but will work in git-bump.
• Configuration settings override command-line defaults
• Each versioning convention has its own increment logic and options