Skip to content
BranchesTags

Repository files navigation

bump-version

bump-version — a utility to automate:

  • versioning in accordance with the Semantic Versioning specification
  • generation of a changelog (Changelog)
  • validation of commit messages against the Conventional Commits specification
  • creation of a version file that can be imported into your program’s code at build time. This makes it possible, for example, to automatically keep the program version displayed by --version or in a GUI up to date
  • generation of Git commits related to a release, for example: chore: release 1.0.0
  • automatic addition of Git tags to commits related to a release

The utility currently only works with Git.

Contents

Versioning

The bump-version utility versions itself. This is a dogfooding practice that lets you verify correct behavior and demonstrate the utility on a real project.

Supported platforms

The utility runs on:

  • Linux (ARM64)
  • Linux (ARMV6L)
  • Linux (x86)
  • Linux (x86_64)
  • macOS (ARM64)
  • macOS (x86_64)
  • Microsoft Windows (x86)
  • Microsoft Windows (x86_64)

In short — anywhere there is a Go compiler.

After building, the build/ directory contains the expected files:

  • linux-amd64/bump-version — Linux (x86_64)
  • macos-amd64/bump-version — macOS (x86_64)
  • macos-arm64/bump-version — macOS (ARM64)
  • windows-amd64/bump-version.exe — Microsoft Windows (x86_64)

Installation and build

How to build the utility

  • Install the latest Go compiler from the official site https://go.dev/dl.
  • Change to the project root directory from the command line.
  • Run:
cd scripts && go run . build && cd ..

After that, compiled artifacts for supported platforms will appear in the build/ directory.

How to install the utility

The utility is statically built and has no runtime dependencies, so installation is simple:

  • Copy the compiled binary to any directory available in PATH (for example /usr/local/bin/ on Unix-like systems or C:\Program Files\bump-version\ on Windows).
  • If necessary, add the directory with the binary to your PATH environment variable.

How to use the utility

Prerequisites

  • The repository must use Git. IMPORTANT: Use git push --tags. The --tags option also pushes the Git tags that are used by this utility to determine the current version.
  • Make atomic commits (one logical change per commit).
  • Follow Semantic Versioning for releases.
  • Write commit messages following Conventional Commits.

The bump-version repository can serve as an example/reference for all these points.

Make atomic commits

An atomic commit contains a single logical change. It should:

  • Address one task: fix a bug, add one small feature, change one config file, etc.
  • Have a meaningful header in Conventional Commits format (kind[scope]: short verb) that reflects the change.
  • Not mix different kinds of changes: for example, do not include formatting, bug fix, and feature in one commit. Semantically different changes should be split into separate commits (e.g., style: format files + fix(scope): correct null pointer).

Why this matters:

  • bump-version analyzes history based on commit kinds (feat/fix/BREAKING CHANGE). If a commit contains multiple semantic types, the utility may misidentify the release type or put changes into the wrong CHANGELOG section.
  • Atomic commits simplify review, rollback, and debugging (easier to find the problematic change via git bisect).
  • When automatically generating a CHANGELOG, each commit lands in the correct section (Features, Bug Fixes, etc.), making the log clear and useful.

Practical recommendations:

  • Make small, frequent commits.
  • If working on a big task — break it into steps and commit iteratively.
  • Use interactive staging/patch tools (git add -p) to separate logically different changes.
  • If needed, add more details in the commit body; keep the header short and Conventional Commit–compliant.

Useful Git tools:

Semantic Versioning specification

For full details read the specification: https://semver.org/lang

Quick summary and practical rules for bump-version:

  • Version format: MAJOR.MINOR.PATCH (e.g., 2.4.1).

    • MAJOR — incompatible API changes.
    • MINOR — added functionality in a backwards-compatible manner.
    • PATCH — backwards-compatible bug fixes.

  • Rules for bumping based on commit history (how bump-version applies them):

    • MAJOR — bump when a BREAKING CHANGE entry is found in the commit body/footer or if there is an exclamation mark after the commit type (e.g., feat!: ... or fix!: ...).
    • MINOR — bump if there are no breaking changes but at least one feat commit.
    • PATCH — bump if there are no breaking changes or feat commits but there are fix commits.
    • No change — if there are no feat/fix/BREAKING CHANGE commits (the utility exits without releasing).

  • Additional notes:

    • Commits like perf, refactor, docs, chore, etc. do not bump the version by default but may be included in the changelog under corresponding sections. You can include such commit types in the CHANGELOG via settings (see utility settings).
    • BREAKING CHANGE counts even if declared in the commit body (for example, after a blank line) and should be explicit — describing the change and why it is incompatible.
    • The v prefix in Git tags (e.g., v1.2.3) is optional and is configurable via the "versionTagFormat" field in the config file. The semantic versioning itself is unaffected by the prefix.

  • Examples:

    • History: one feat: add export and several fix: → minor release (x.Y+1.0).
    • History: refactor: restructure internals and docs: → no version change by default.
    • History: feat!: change API signature or presence of BREAKING CHANGE: → major release (X+1.0.0).

Following these rules and atomic commits ensures correct operation of bump-version and a useful, readable changelog.

Conventional Commits specification

For full details read the specification: https://www.conventionalcommits.org/en/v1.0.0

In short:

Commit header format:

commit_kind(scope): commit_title

commit_body

Scope and body are optional.

Scope is encouraged — it indicates which module or area the commit affects.

The header must start with an imperative present-tense verb, without a trailing period, starting with a lowercase letter. Scope is an abstract module name or unique source file name.

Brief explanation of commit kinds:

  • feat — new features that change program functionality. Example: feat: add user authentication

  • fix — bug fixes. Example: fix: resolve crash on login

  • docs — documentation changes. Example: docs: add installation instructions to README.md

  • style — formatting, style fixes not affecting logic. Example: style: format code

  • refactor — code changes that neither add features nor fix bugs. Example: refactor: simplify user service logic

  • perf — changes that improve performance. Example: perf: optimize image loading

  • test — adding or changing tests. Example: test: add unit tests for user model

  • build — changes to build system or external dependencies. Example: build: update Makefile configuration

  • ci — changes to CI configuration. Example: ci: add linting step to CI pipeline

  • chore — housekeeping tasks not affecting product source code. Example: chore: update dependencies

  • revert — revert previous changes. Example:

    revert: revert "feat: add user authentication"

Refs: 532a023, 22aeae8

    The Refs attribute is necessary for this utility to determine which commits are reverted.

  • BREAKING CHANGE — description of incompatible changes (may be in commit body or as a separate header). Example: BREAKING CHANGE: The API endpoint has changed from /api/v1/users to /api/v2/users.

Utility syntax

  • Simple release generating all necessary files:
bump-version

This command performs auto-detection from commits, updates the version file, updates the Changelog, creates a release commit, and adds a Git tag.

  • Show the changelog for this release without writing it to the Changelog file:
bump-version preview-changelog
  • Add a Git hook to validate commit messages before each commit:
bump-version add-hook

Hooks may interfere with squashing and frequent rebases, so the hook is not installed by default. To just validate commits since the last release use bump-version lint. Also, if ignoreInvalidCommits is not set to true in the config file, the utility will fail on invalid commits.

  • Remove the Git hook that validates commit messages before each commit:
bump-version remove-hook
  • Validate commits since the last release (no release), listing commits that do not match Conventional Commits:
bump-version lint
  • Validate all commits in history (no release), listing commits that do not match Conventional Commits:
bump-version lint-all
  • Validate the provided commit message:
bump-version lint-commit "fix: resolve crash on login"
  • Show the current version of your program and exit:
bump-version my-version
  • Show the next version of your program and exit (no changes applied):
bump-version next-version
  • Show help:
bump-version help
  • Show utility version:
bump-version version
  • Use a different config file:
bump-version command -config other-bump-version-config.cfg
  • Add a config file bump-version.cfg to the project root:
bump-version init-config
  • The -force option suppresses the prompts like "Are you sure you want to overwrite this file?"
bump-version -force init-config

Utility settings

The config file must be at the project root named bump-version.cfg. If not found, default configuration is used.

The -config option points the utility to another config file.

Default configuration:

Config file fields:

  • version — configuration file version.
  • versionFilenames — comma-separated names of the version files.
  • changeLogFilename — name of the ChangeLog file.
  • ignoreInvalidCommits — ignore invalid commits (do not fail on them).
  • versionTagFormat — Git tag format for releases. Substitution {version} is replaced with the semantic version X.Y.Z.
  • allowedCommitKinds — comma-separated list of allowed commit kinds.
  • bumpVersionCommit — version bump commit message format.
  • shouldPushToOrigin — should this utility push the main branch on version bump.

Each field present in the configuration file overrides the default.

How the utility determines release type

bump-version scans commits since the last release and determines the required version bump based on Conventional Commit types:

  • If there is at least one commit with BREAKING CHANGE or an exclamation mark after the commit kind — bump MAJOR.
  • Else if there are feat commits — bump MINOR.
  • Else if there are fix commits — bump PATCH.
  • If there are no relevant commits — the version does not change (the utility will warn and exit successfully without making changes).

Example generated CHANGELOG file

# Changelog

## [2.76.0](///compare/v2.75.0...v2.76.0) (2025-06-06)

### Features

* avoid rendering of AppConsole when it is hidden (its state is preserved though) b3f62f98
* avoid rendering of ToTop button if it is hidden f67557ab
* disable API echo in Overlay Console by default 00ef9def
* **KauSection:** add Smoke icon indicator and the ability to search sensors with smoke state 8bf88509
* **KauSection:** use proportional font for hex sensor state, also shade zero nibbles in gray 0f99f89d
* make searching of items by empty queries faster ea585088


### Bug Fixes

* **Settings:** ensure current theme hover re-renders as soon as chosen theme changes 72e32f98

Files generated by the utility

  • CHANGELOG.md — automatically generated changelog grouped by versions and change kinds with commit hashes.
  • Version file (e.g., VERSION) — contains a single line with the current version.
  • A Git commit with the release message (by default chore: release X.Y.Z).
  • A Git tag with the release name (e.g., vX.Y.Z).

Frequently Asked Questions (FAQ)

  • Question: What happens if there are no commits matching Conventional Commits?

    • Answer: The utility prints an error or a warning about ignored commits. You will need to run an interactive rebase (git rebase -i) to fix the commits.

  • Question: I bumped the new version too early. What should I do?

    • Answer: Run the bump-version cancel command.

Contributors

About

A Go CLI tool for automating semantic versioning, changelog generation, and Conventional Commits validation with Git release support

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages