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.

Finishing an interrupted bump#

If a pre-commit hook fails, or git cannot stage or commit the release files, the version replacements remain in the working tree, while the commit and tag are not created. The error names the command that failed, shows its output, and ends with the way out. Fix the failed check, then resume the release without replacing versions again:

bumpversion finalize --allow-dirty

finalize treats the latest tag as the previous version and the configured current_version as the release target. It reruns pre-commit hooks, commits the configured files and additional_files, creates the configured tag, and runs post-commit hooks. It does not rewrite files or rerun setup hooks.

The command honors the configured commit and tag values and their command-line overrides. It requires an existing previous version tag and refuses to finalize when current_version already matches the latest tag.

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.