Bump is a Go CLI that reads and increments version strings in common project files

What it is

Bump is a single-purpose command-line program written in Go 1.24.5. It takes a version string such as v1.0.0, applies the requested bump operations (one of major/minor/patch, optionally combined with pre-release steps), prints the new value and, when -write is set — or BUMP_ALWAYS_WRITE makes it the default — writes it back to the file that held the old one.

The default input is a plain text VERSION file in the current working directory. The tool also understands six common project files by name — go.mod, package.json, pom.xml, Chart.yaml, and Dockerfile alongside VERSION — so it can bump the version string inside those files, not just a separate sidecar file.

The repository is organized into two packages. The top-level package holds the CLI: flag parsing, environment handling, validation of which flags may combine, and output formatting (main.go). A nested bump/ package contains the real work — reading files, parsing version strings, applying increments, and saving results back.

How it works

The core type is Version, defined in bump/version.go. It holds parsed fields for Major, Minor, Patch, Alpha, Beta, RC and Preview, plus the raw bytes of whatever file was loaded. A mutex guards concurrent access, which matters because a single invocation can load, parse, bump, and save in sequence.

The lifecycle is visible in main.go. After flags are parsed:

1. NewVersion() loads the input file with LoadFile and parses it.
2. If the input file is missing, its name ends with VERSION, and initialization is allowed (-init or BUMP_INIT_ON_NOT_FOUND), a fresh version like v0.0.0-beta.1 is written first; for other missing files it prints an error and exits.
3. validate() counts how many bump operations were requested and rejects conflicting combinations — for instance, only one of -major, -minor, -patch may be used at once.
4. run() applies the chosen increments through methods like BumpPatch(), BumpAlpha() and BumpRC() in bump/version_bump.go.
5. finish() prints a summary such as Bumped v1.0.2 → v1.0.3 and, when -write is set, saves the file.

Some bump methods reset lower-order fields. Bumping major zeroes minor, patch, and every pre-release field; bumping alpha increments Alpha and adjusts the output form (FormB, or FormE if the current form is RC).

Formats it understands

Version strings are matched from most complex to least complex, per bump/attributes.go and the README:

1. v1.2.3-beta.4-alpha.5
2. v1.2.3-alpha.1
3. v1.2.3-beta.2
4. v1.2.3-rc.1
5. v1.2.3-preview.7
6. v1.2.3

The ordering matters: checking the simpler patterns first would misread a detailed pre-release string as a plain semver. The package also recognizes shorthand forms like two-part versions (1.24) and three-part versions without a v prefix, which is how it can bump something like the Go directive in a go.mod.

Saving is file-aware through Save() in bump/version_save.go, which switches on the base filename. A plain VERSION file gets its whole contents replaced with the new version string. For structured files, only the relevant key changes: the "version" field of a parsed JSON object for package.json, the <version> element in Maven's pom.xml, and so on.

Environment control

The CLI is designed to be driven by environment variables rather than edited flags alone. The README documents ten settings, including:

• BUMP_ALWAYS_WRITE — treat every invocation as if -write were passed
• BUMP_DEFAULT_INPUT — override the default input file path
• BUMP_NO_ALPHA, BUMP_NO_BETA, BUMP_NO_RC, BUMP_NO_PREVIEW — disable individual pre-release steps
• BUMP_NO_ALPHA_BETA — block combining alpha and beta in one call

The stated purpose is to keep odd intermediate versions like v1.0.1-beta.3-alpha-3 out of a release history when pipelines might otherwise combine flags. Running bump -env prints the current effective configuration, and validate() reports explicitly when every requested operation was suppressed by an environment variable rather than silently doing nothing.

Using it in a pipeline

Because success and failure map to exit codes 0 and 1, Bump is meant for DevOps workflows: a failed parse or validation stops the build. Two flags support automation directly:

• -check prints the current version string and exits; an error code signals an invalid string.
• -json emits indented JSON output instead of plain text.

The README notes that -json does not write JSON to the input file — it only changes what is printed. Writing still produces plain text in whatever format the target file expects.

Building and testing

The Makefile builds stripped binaries for five targets: darwin-amd64, darwin-arm64, linux-amd64, linux-arm64, and windows-amd64, then installs the matching one into GOBIN. Release downloads are offered per platform in the README, pinned to v1.1.0.

Testing is a first-class concern of this repository. The Makefile's test target runs CLI tests, unit tests, benchmarks, fuzz testing and integration tests, each writing its results into test-results/. There are separate shell scripts (test.sh, test_funcs.sh, test_scenarios.sh) that exercise the binary end to end across fourteen named scenarios. A GitHub Actions workflow at .github/workflows/go-bump.yml runs CI.

The README also shows a pattern for consuming the produced version from Go code, embedding the VERSION file with //go:embed VERSION and trimming whitespace before returning it — a natural fit given Bump's own binary embeds its version string the same way (main.go, via BinaryVersion()).

Getting started

Installation is either through Go or a release download:

go install github.com/andreimerlescu/bump@latest

Then, inside any project that keeps a plain-text VERSION file:

bump -check        # prints the current version; exit code signals validity
bump -patch        # previews v1.0.2 → v1.0.3 without saving
bump -patch -write # saves the new version back to VERSION

For a project that keeps a bumpable version string in go.mod (the Go directive) or package.json, point -in at that file and use -write; Bump will edit only the relevant field.