CLI reference#

$ bumpversion --help
 
bump git version
 
Usage: bumpversion [OPTIONS] [ARGS]... [COMMAND]
 
Commands:
  major
  minor
  patch
  show
  show-bump
  bump
  help       Print this message or the help of the given subcommand(s)
 
Arguments:
  [ARGS]...
 
Options:
      --dir <DIR>
          repository directory to run bumpversion in [env: BUMPVERSION_DIR=]
      --config-file <CONFIG_FILE>
          config file to read most of the variables from [env: BUMPVERSION_CONFIG_FILE=]
      --color <COLOR_CHOICE>
          enable or disable color [env: BUMPVERSION_COLOR=]
  -v, --verbose...
          Increase logging verbosity
  -q, --quiet...
          Decrease logging verbosity
      --log <LOG_LEVEL>
          Log level. When using a more sophisticated logging setup using RUST_LOG environment variable, this option is overwritten. [env: BUMPVERSION_LOG_LEVEL=]
      --allow-dirty
          don't abort if working directory is dirty [env: BUMPVERSION_ALLOW_DIRTY=]
      --no-allow-dirty
          explicitly abort if dirty [env: BUMPVERSION_NO_ALLOW_DIRTY=]
      --current-version <CURRENT_VERSION>
          version that needs to be updated [env: BUMPVERSION_CURRENT_VERSION=]
      --new-version <NEW_VERSION>
          new version that should be in the files [env: BUMPVERSION_NEW_VERSION=]
      --parse <PARSE_VERSION_PATTERN>
          regex parsing the version string [env: BUMPVERSION_PARSE=]
      --serialize <SERIALIZE_VERSION_PATTERNS>
          how to format what is parsed back to a version [env: BUMPVERSION_SERIALIZE=]
      --search <SEARCH>
          template for complete string to search [env: BUMPVERSION_SEARCH=]
      --replace <REPLACE>
          template for complete string to replace [env: BUMPVERSION_REPLACE=]
      --regex
          treat the search parameter as a regular expression [env: BUMPVERSION_REGEX=]
      --no-regex
          explicitly do not treat the search parameter as a regular expression [env: BUMPVERSION_NO_REGEX=]
      --no-configured-files
          only replace the version in files specified on the command line, ignoring the files from the configuration file [env: BUMPVERSION_NO_CONFIGURED_FILES=]
      --ignore-missing-files
          ignore any missing files when searching and replacing in files [env: BUMPVERSION_IGNORE_MISSING_FILES=]
      --no-ignore-missing-files
          do not allow missing files when searching and replacing in files [env: BUMPVERSION_NO_IGNORE_MISSING_FILES=]
      --ignore-missing-version
          ignore any missing versions when searching and replacing in files [env: BUMPVERSION_IGNORE_MISSING_VERSION=]
      --no-ignore-missing-version
          do not allow missing versions when searching and replacing in files [env: BUMPVERSION_NO_IGNORE_MISSING_VERSION=]
  -n, --dry-run
          don't write any files, just pretend. [env: BUMPVERSION_DRY_RUN=]
      --commit
          commit to version control [env: BUMPVERSION_COMMIT=]
      --no-commit
          do not commit to version control [env: BUMPVERSION_NO_COMMIT=]
      --tag
          create a tag in version control [env: BUMPVERSION_TAG=]
      --no-tag
          do not create a tag in version control [env: BUMPVERSION_NO_TAG=]
      --sign-tags
          sign tags if created [env: BUMPVERSION_SIGN_TAGS=]
      --no-sign-tags
          do not sign tags if created [env: BUMPVERSION_NO_SIGN_TAGS=]
      --tag-name <TAG_NAME>
          tag name (only works with --tag) [env: BUMPVERSION_TAG_NAME=]
      --tag-message <TAG_MESSAGE>
          tag message [env: BUMPVERSION_TAG_MESSAGE=]
  -m, --message <COMMIT_MESSAGE>
          commit message [env: BUMPVERSION_MESSAGE=]
      --commit-args <COMMIT_ARGS>
          extra arguments to commit command [env: BUMPVERSION_COMMIT_ARGS=]
  -h, --help
          Print help
  -V, --version
          Print version

Every flag below is global: accepted at the top level and on every subcommand alike. Each also has an environment variable, named BUMPVERSION_ plus the flag in upper snake case.

General#

Flag	Value	Description
`--dir`	path	Repository directory to run in
`--color`	`auto`, `always`, `always-ansi`, `never`	Enable or disable color. Defaults to `auto`, which is on only when stdout is a terminal
`-v`, `--verbose`	repeatable	Increase verbosity
`-q`, `--quiet`	repeatable	Decrease verbosity
`--log`	level	Tracing log level. Also accepted as `--log-level`
`-h`, `--help`		Print help
`-V`, `--version`		Print version

Version#

Flag	Value	Description
`--current-version`	string	Version to bump from, overriding the config
`--new-version`	string	Version to write, skipping component selection
`--parse`	regex	Regex parsing the version string
`--serialize`	string	How to format components back into a version. Repeatable

Files#

Flag	Value	Description
`--search`	template	String to search for
`--replace`	template	String to replace it with
`--no-configured-files`	flag	Only rewrite files named on the command line
`--ignore-missing-files` / `--no-ignore-missing-files`	flag	Whether a missing file is an error
`--ignore-missing-version` / `--no-ignore-missing-version`	flag	Whether a missing version in a file is an error

Version control#

Flag	Value	Description
`-n`, `--dry-run`	flag	Write nothing; just report
`--allow-dirty` / `--no-allow-dirty`	flag	Whether to proceed on an unclean working tree
`--commit` / `--no-commit`	flag	Whether to commit
`--tag` / `--no-tag`	flag	Whether to tag
`--sign-tags` / `--no-sign-tags`	flag	Whether to sign the tag
`--tag-name`	template	Tag name
`-m`, `--message`	template	Commit message
`--commit-args`	string	Extra arguments for `git commit`

Each --x / --no-x pair overrides the corresponding config key for one run; without either, the config value stands.

Verbosity#

The report is off by default. This is the single most surprising thing about the tool:

Flags	Output
(none)	Nothing. A successful bump is completely silent
`-v`	The full report: versions, per-file diffs, commit, tag, hooks
`-vv`	Adds the per-component breakdown under each version
`-vvv` and above	Accepted, identical to `-vv`
`-q`	Same as the default

-q and -v cannot be combined; doing so is a usage error.

--log is separate: it controls tracing diagnostics from the library, not the report. It defaults to WARN, which is why a mismatch between the configured version and the last tag shows up even in an otherwise silent run:

WARN bumpversion::common: version 1.4.2 from config does not match last tagged version (1.4.3)

RUST_LOG overrides --log when set, taking the same directive syntax as any tracing filter — RUST_LOG=bumpversion=debug.

Exit codes#

Code	Meaning
`0`	Success. Also `--help`, `--version`, and a `show` with an unknown variable
`1`	The run failed — no config file, unclean tree, unknown component, a hook that failed
`2`	The command line could not be parsed — unknown flag, bad `--color` value, missing component

Nothing finer distinguishes the failure modes, so a script that needs to tell “dirty tree” from “missing config” has to match on the message.

Common exit-1 messages:

Message	Cause
`missing config file`	No recognized config file in the directory
`Working directory is not clean:`	Uncommitted changes; pass `--allow-dirty`
`missing version component to bump`	No component given and no `--new-version`
`missing current version`	No `current_version` in the config or on the command line
`failed to parse current version`	`current_version` does not match the `parse` pattern
`the component has already the maximum value ...`	A `values` component is already at its last entry

Requirements#

bumpversion opens the Git repository before doing anything, so every command — including show — must run inside one.