Callback to be used for formatting a branch name before template substitution


This option is used only with Release is a git tag or Read some file content as current version versioning schemas.


str or callable

Default value#



It is possible to use (see Development releases from any branch) branch name in version number.

But branches should have PEP 440 compatible name, like:

  • alpha

  • beta

  • rc

  • preview

  • pre

  • post

  • dev

In case of using branch names like feature/ABC-123 or bugfix/ABC-123, you’ll get version number which pip cannot understand.

To fix that you can define a callback which will receive current branch name and return a properly formatted one:

import re

def format_branch_name(name):
    # If branch has name like "bugfix/issue-1234-bug-title", take only "1234" part
    pattern = re.compile("^(bugfix|feature)\/issue-(?P<branch>[0-9]+)-\S+")

    match =
    if match:

    # function is called even if branch name is not used in a current template
    # just left properly named branches intact
    if name in ["master", "dev"]:
        return name

    # fail in case of wrong branch names like "bugfix/issue-unknown"
    raise ValueError(f"Wrong branch name: {name}")


Please pay attention to build-backend item in your config, it is important for setuptools-git-versioning to access your module source code.

Possible values#

  • None

    Disables this feature

  • function/lambda ( only)

  • function full name in format "some.module:function_name"

    Function should have signature (str) -> str. It accepts original branch name and returns formatted one


    Exception will be raised if module or function/lambda is missing or has invalid signature

  • regexp like ".*(?P<branch>\d+).*"

    Regexp should have capture group named "branch" matching the expected branch name


    Exception will be raised if regexp is invalid or does not have expected capture group


    Exception will also be raised if branch name does not match regexp. So this regexp should be able to handle all possible branches in the repo