Skip to content

Hooks

Hook Suites

A hook suite is a list of hooks to run sequentially. A hook is either an individual shell command or an executable script.

There are three hook suites: setup, pre-commit, and post-commit. During the version increment process this is the order of operations:

  1. Run setup hooks
  2. Increment version
  3. Change files
  4. Run pre-commit hooks
  5. Commit and tag
  6. Run post-commit hooks

Note

Don’t confuse the pre-commit and post-commit hook suites with Git pre- and post-commit hooks. Those hook suites are named for their adjacency to the commit and tag operation.

Configuration

Configure each hook suite with the setup_hooks, pre_commit_hooks, or post_commit_hooks keys.

Each suite takes a list of strings. The strings may be individual commands:

Calling individual commands
[tool.bumpversion]
setup_hooks = [
    "git config --global user.email \"bump-my-version@github.actions\"",
    "git config --global user.name \"Testing Git\"",
    "git --version",
    "git config --list",
]
pre_commit_hooks = ["cat CHANGELOG.md"]
post_commit_hooks = ["echo Done"]

or the path to an executable script:

Calling a shell script
[tool.bumpversion]
setup_hooks = ["path/to/setup.sh"]
pre_commit_hooks = ["path/to/pre-commit.sh"]
post_commit_hooks = ["path/to/post-commit.sh"]

Note

You can make a script executable using the following steps:

  1. Add a shebang line to the top like #!/bin/bash
  2. Run chmod u+x path/to/script.sh to set the executable bit

Hook Environments

Each hook has these environment variables set when executed.

Inherited environment

All environment variables set before bump-my-version was run are available.

Date and time fields

BVHOOK_NOW
The ISO-8601-formatted current local time without a time zone reference.
BVHOOK_UTCNOW
The ISO-8601-formatted current local time in the UTC time zone.

Source code management fields

Note

These fields will only have values if the code is in a Git or Mercurial repository.

BVHOOK_COMMIT_SHA
The latest commit reference.
BHOOK_DISTANCE_TO_LATEST_TAG
The number of commits since the latest tag.
BVHOOK_IS_DIRTY
A boolean indicating if the current repository has pending changes.
BVHOOK_BRANCH_NAME
The current branch name.
BVHOOK_SHORT_BRANCH_NAME
The current branch name, converted to lowercase, with non-alphanumeric characters removed and truncated to 20 characters. For example, feature/MY-long_branch-name would become featuremylongbranchn.

Current version fields

BVHOOK_CURRENT_VERSION
The current version serialized as a string
BVHOOK_CURRENT_TAG
The current tag
BVHOOK_CURRENT_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_CURRENT_MAJOR, BVHOOK_CURRENT_MINOR, and BVHOOK_CURRENT_PATCH available.

New version fields

Note

These are not available in the setup hook suite.

BVHOOK_NEW_VERSION
The new version serialized as a string
BVHOOK_NEW_TAG
The new tag
BVHOOK_NEW_<version component>
Each version component defined by the version configuration parsing regular expression. The default configuration would have BVHOOK_NEW_MAJOR, BVHOOK_NEW_MINOR, and BVHOOK_NEW_PATCH available.

Outputs

The stdout and stderr streams are echoed to the console if you pass the -vv option.

Dry-runs

Bump my version does not execute any hooks during a dry run. With the verbose output option it will state which hooks it would have run.

Comments