bump | Ballast Development

Overview

I got tired of bespoke scripts and slightly-different regex per repo just to bump a version. bump is dead simple and without opinion. Everyone versions differently and that’s okay — a sprinkle of convention and a large helping of automation, and you never have to think about versions again.

The sweet spot is when banal updates move programatically.

Declarative — human-readable bump.toml
Composable — construct your version (PRODUCT.RELEASE.HOTFIX, mix calendar and custom keys)
Flexible — multiple bumpfiles so one repo can version several things
Integrated — bump print and bump emit feed the version into source, Make, CMake, and CI
Compatible — bump print --semver gives the first three base components to SemVer-aware tools

Quick start

Linux, macOS, or WSL:

curl -fsSL https://raw.githubusercontent.com/krakjn/bump/main/install/get_bump.sh | sh

Windows (PowerShell): irm https://raw.githubusercontent.com/krakjn/bump/main/install/get_bump.ps1 | iex

bump init          # creates bump.toml with SemVer defaults
bump print         # v0.1.0
bump patch         # 0.1.0 -> 0.1.1
bump print --full  # prefix + base + phase + suffix + timestamp

Pass a path on any command to use a non-default bumpfile: bump patch lib/bump.toml.

Bumpfile

bump init writes a bumpfile (default bump.toml). Rename it, or keep several in one repo.

Section	Purpose
prefix	Literal prefix prepended to the composed version
`[base]`	Version numbers — keys and TOML order define cascade
`[phase]`	Pre-release name and distance (`-alpha.1`)
`[suffix]`	Git metadata appended at print time (`git_sha` or `branch`)
`[timestamp]`	Last-bump timestamp, shown with `--with timestamp`
`[label]`	Where an ephemeral `--label` value injects at print time

Base keys are yours. TOML order is cascade order: bumping a key increments it and zeroes everything after it.

SemVer — major, minor, patch (defaults from bump init)
CalVer — year, month, day sync to UTC on every bump
Custom — any names you want (alpha, beta, gamma)

Date keys print zero-padded (2026.02.05); other keys print as integers.

Commands

Subcommands for base keys are generated from your bumpfile. Run bump --help in a repo to see that file’s list.

Print (p) — composed version, no trailing newline. Safe for $(bump p), Make, and CMake.

bump print [BUMPFILE]
bump p --only base
bump print --without prefix --with suffix
bump print --full
bump print --semver
bump print --label DEV

Bump — updates the bumpfile.

bump major     # 1.0.0 -> 2.0.0
bump minor
bump patch
bump date      # CalVer: sync year/month/day to UTC
bump phase alpha
bump patch --if-changed-from main lib/bump.toml

Formal base bumps always clear phase. bump date is the exception: if date keys are already today, it increments phase instead.

Emit — write language templates or structured markup. Prefer emitting at build time and gitignoring the output.

bump emit c -o version.h
bump emit go -o version.go
bump emit json
bump emit python --prefix "MYLIB_" --case uppercase -o version.py

Formats: raw, c, java, csharp, go, python, json, toml, yaml.

Also — bump tag writes an annotated git tag; bump update Cargo.toml / pyproject.toml writes the current version into the manifest.

CI

The composite action installs bump for the job’s OS and arch:

- uses: krakjn/bump@v9

Pass a token if you want to skip unauthenticated GitHub API rate limits:

- uses: krakjn/bump@v9
  with:
    token: ${{ secrets.YOUR_TOKEN_HERE }}

Inject run info without persisting it — labels are print-time only:

bump print --label "-${GITHUB_RUN_NUMBER}"
bump print --full --label "+ci"

More patterns — release pipelines, monorepo selective bumps, Docker ARG VERSION — live in the workflow guide.