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 src.timharek.no/tim/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://src.timharek.no/tim/git-bump/releases/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} (only this format is supported)
• 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 the current directory
2. $XDG_CONFIG_HOME/git-bump/gitbump.toml (macOS: ~/Library/Application Support/git-bump/gitbump.toml)
3. ~/.config/git-bump/gitbump.toml
4. ~/gitbump.toml

The local file is named .gitbump.toml, global ones gitbump.toml. TOML is the only supported format. The first file found wins; it is not merged with the others.

Settings can also be overridden with environment variables prefixed with GITBUMP_, e.g. GITBUMP_GIT_AUTO_PUSH=true or GITBUMP_VERSIONING_CONVENTION=calver.

Show the effective configuration, including where it was loaded from:

git bump config

Verify that the loaded configuration is valid (parses, and the convention, format, and timezone are accepted):

git bump check

Usage

# Get help
git bump -h

# Bump version (uses convention-specific default increment)
git bump
# Asks for confirmation before creating the tag; prints just the new tag:
# v0.0.1 (semver) or release2025.07.11 (calver)

# Skip the confirmation prompt (use in scripts)
git bump --force

# 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

# Skip the confirmation prompt
git bump undo --force

# 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: Restarts the micro cycle each month — the first release of a month has no micro segment (vYYYY.MM), later releases increment it (vYYYY.MM.1, vYYYY.MM.2, ...). This also applies when the previous tag was day-based, e.g. from an earlier YYYY.MM.DD format.
• 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