Commits and tags#

bumpversion can finish a bump by committing the rewritten files and tagging the commit. Both are off by default — a bare bumpversion patch only edits files.

[tool.bumpversion]
commit = true
tag = true

On the command line, --commit / --no-commit and --tag / --no-tag override the config for one run.

The dirty-tree check#

Before doing anything, bumpversion refuses to run if the working tree has uncommitted changes:

Error:
   0: Working directory is not clean:

This is deliberate: a release commit should contain the version bump and nothing else. Set allow_dirty = true, or pass --allow-dirty, when you genuinely want to bundle other staged work into the release commit.

The check is skipped for the read-only commands, show and show-bump.

What gets committed#

Everything the run rewrote, plus the config file, plus anything in additional_files. The verbose report lists it explicitly before the commit message:

$ bumpversion --dry-run -v bump minor
 
 [DRY-RUN] [current version]
 [DRY-RUN] 	0.5.0
 [DRY-RUN] [setup]
 [DRY-RUN] 	running test -z "$(git status --porcelain --untracked-files=no)"
 [DRY-RUN] [new version]
 [DRY-RUN] 	0.6.0
 [DRY-RUN] 
 [DRY-RUN] [./src/version.rs]
 [DRY-RUN] 	replacing `{current_version}` (0.5.0) with `{new_version}` (0.6.0)
 [DRY-RUN] 
 [DRY-RUN] 	Differences (-before|+after):
 [DRY-RUN] 	-pub const VERSION: &str = "0.5.0";
 [DRY-RUN] 	+pub const VERSION: &str = "0.6.0";
 [DRY-RUN] 
 [DRY-RUN] [./.bumpversion.toml]
 [DRY-RUN] 	replacing `{current_version}` (0.5.0) with `{new_version}` (0.6.0)
 [DRY-RUN] 
 [DRY-RUN] 	Differences (-before|+after):
 [DRY-RUN] 	 [tool.bumpversion]
 [DRY-RUN] 	-current_version = "0.5.0"
 [DRY-RUN] 	+current_version = "0.6.0"
 [DRY-RUN] 	 commit = true
 [DRY-RUN] 	 tag = true
 [DRY-RUN] 	 tag_name = "v{new_version}"
 [DRY-RUN] 	 message = "chore(release): {current_version} → {new_version}"
 [DRY-RUN] [pre-commit]
 [DRY-RUN] 	running sh scripts/changelog.sh $BVHOOK_NEW_VERSION
 [DRY-RUN] [commit]
 [DRY-RUN] 	   add ./src/version.rs
 [DRY-RUN] 	   add ./CHANGELOG.md
 [DRY-RUN] 	   add ./.bumpversion.toml
 [DRY-RUN] 	commit chore(release): 0.5.0 → 0.6.0
 [DRY-RUN] [tag]
 [DRY-RUN] 	tag = v0.6.0
 [DRY-RUN] 	message = Bump version: 0.5.0 → 0.6.0
 [DRY-RUN] 	sign = false
 [DRY-RUN] [post-commit]
 [DRY-RUN] 	running echo released $BVHOOK_NEW_VERSION

CHANGELOG.md appears in that list only because the example puts it in additional_files — a pre-commit hook rewrites it, but no [[files]] entry produces it.

Messages and tag names#

Three templates control the VCS output:

They accept the full placeholder set, so a Conventional Commits subject or a date-stamped tag is a one-liner:

message  = "chore(release): {current_version} → {new_version}"
tag_name = "release/{new_version}"

A project that tags without the v prefix sets tag_name = "{new_version}".

If the tag already exists, the report says so and the tag is not recreated; the commit still happens.

Signing#

sign_tags = true (the alias sign_tag is also accepted) creates a signed tag, using whatever signing key Git is configured to use. The verbose report’s [tag] block shows sign = true or sign = false for every run.

Extra commit arguments#

commit_args is appended to the git commit invocation. It is split like a shell command line:

commit_args = "--no-verify"

That example skips your repository’s pre-commit Git hooks for the release commit — useful when a formatter hook would otherwise fight the bump.

Environment passed to the commit#

The git commit subprocess receives BUMPVERSION_CURRENT_VERSION and BUMPVERSION_NEW_VERSION, so a commit-msg or prepare-commit-msg Git hook can tell a release commit from an ordinary one. These are separate from the BVHOOK_* variables given to bumpversion’s own hooks.