CLI Reference¶

Details for each command. See Quickstart for a walkthrough.

Top-level command¶

bumpwright¶

Suggest and apply semantic version bumps.

Args:

ctx: Click execution context. config: Path to the configuration file used for the run. Defaults to

bumpwright.toml.

quiet: Reduce log output to warnings and errors. verbose: Increase log output to show debug messages.

bumpwright [OPTIONS] COMMAND [ARGS]...

Options

--config <config>¶

Path to configuration file. See Configuration Reference for details.

Default:: 'bumpwright.toml'

--quiet¶: Only display warnings and errors.

--verbose¶: Show debug messages.

bump¶

Update version metadata and optionally commit and tag the change.

Args:: args: Parsed command-line arguments from cli(). **kwargs: Command-specific options. Notable parameters include:

base (str | None): Git reference used as the comparison base when inferring the bump level. Defaults to the latest release commit or HEAD^.

head (str): Git reference representing the working tree. Defaults to HEAD.

output_fmt (str): Output format: text (default), md for Markdown, or json for machine-readable output.

repo_url (str | None): Base repository URL used to build commit links in Markdown output. Overrides [changelog].repo_url when provided.

decide (bool): When True, only report the bump level without modifying any files.

enable_analyser (tuple[str, …]): Names of analysers to enable in addition to those configured.

disable_analyser (tuple[str, …]): Names of analysers to disable even if configured.

no_impl_change_patch (bool): When True, ignore implementation-only changes to public symbols when determining the bump level.

pyproject (str): Path to pyproject.toml. Defaults to pyproject.toml.

version_path (tuple[str, …]): Extra glob patterns for files whose version fields should be updated. Defaults include pyproject.toml, setup.py, setup.cfg, and any __init__.py, version.py, or _version.py files.

version_ignore (tuple[str, …]): Glob patterns for paths to exclude from version updates.

commit (bool): Create a git commit containing the version change.

tag (bool): Create a git tag for the new version.

dry_run (bool): Show the new version without modifying files.

changelog (str | None): Write release notes to the given file or stdout when - is provided.

changelog_template (str | None): Path to a Jinja2 template used to render changelog entries. Defaults to the built-in template.

changelog_exclude (tuple[str, …]): Regex patterns of commit subjects to omit from changelog entries.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright bump [OPTIONS]

Options

--base <base>¶: Base git reference when auto-deciding the level. Defaults to the last release commit or the previous commit (HEAD^).

--head <head>¶

Head git reference.

Default:: 'HEAD'

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--repo-url <repo_url>¶: Base repository URL for linking commit hashes in Markdown output. Can also be set via [changelog].repo_url in configuration.

--explain¶: Show reasoning behind the selected bump level.

--no-impl-change-patch¶: Ignore implementation-only changes to public symbols.

--enable-analyser <enable_analyser>¶: Enable analyser NAME (repeatable) in addition to configuration.

--disable-analyser <disable_analyser>¶: Disable analyser NAME (repeatable) even if configured.

--pyproject <pyproject>¶

Path to the project’s pyproject.toml file.

Default:: 'pyproject.toml'

--version-path <version_path>¶: Additional glob pattern for files containing the project version (repeatable). Defaults include pyproject.toml, setup.py, setup.cfg, and any __init__.py, version.py, or _version.py files.

--version-ignore <version_ignore>¶: Glob pattern for paths to exclude from version updates (repeatable).

--commit¶: Create a git commit for the version change.

--tag¶: Create a git tag for the new version.

--dry-run¶: Display the new version without modifying any files.

--changelog <FILE>¶: Append release notes to FILE or stdout when no path is given. Defaults to [changelog].path in configuration when omitted.

--changelog-template <changelog_template>¶: Jinja2 template file for changelog entries; defaults to the built-in template or [changelog].template when configured.

--changelog-exclude <changelog_exclude>¶: Regex pattern for commit subjects to exclude from changelog (repeatable). Combined with patterns from [changelog].exclude.

decide¶

Suggest a version bump without modifying files.

bumpwright decide [OPTIONS]

Options

--base <base>¶: Base git reference when auto-deciding the level. Defaults to the last release commit or the previous commit (HEAD^).

--head <head>¶

Head git reference.

Default:: 'HEAD'

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--emit-changelog¶: Print expected changelog for the suggested version.

--explain¶: Show reasoning behind the selected bump level.

--no-impl-change-patch¶: Ignore implementation-only changes to public symbols.

--repo-url <repo_url>¶: Base repository URL for linking commit hashes in Markdown output. Can also be set via [changelog].repo_url in configuration.

--changelog-template <changelog_template>¶: Jinja2 template file for changelog entries; defaults to the built-in template or [changelog].template when configured.

--changelog-exclude <changelog_exclude>¶: Regex pattern for commit subjects to exclude from changelog (repeatable).

--enable-analyser <enable_analyser>¶: Enable analyser NAME (repeatable) in addition to configuration.

--disable-analyser <disable_analyser>¶: Disable analyser NAME (repeatable) even if configured.

history¶

List existing git tags, roll back a release, or purge bumpwright state.

Args:: args: Parsed command-line arguments from cli(). output_fmt: Desired output format. stats: Whether to include diff statistics between tags. rollback: Tag to remove and restore to the previous commit. purge: Remove all bumpwright release tags and reset versioned files.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright history [OPTIONS]

Options

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--local-time¶: Display commit dates in local time instead of ISO-8601.

--stats¶: Include line change statistics between successive tags.

--rollback <TAG>¶: Delete TAG and restore versioned files to the previous commit.

--purge¶: Remove all bumpwright release tags and commits, restoring versioned files.

init¶

Create a baseline release commit.

Args:: args: Parsed command-line arguments from cli(). summary: Summary output format.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright init [OPTIONS]

Options

--summary <summary>¶

Show project summary after initialisation in the chosen format.

Options:: table | json

init¶

Create a baseline release commit.

bumpwright init¶

Create a baseline release commit.

Args:: args: Parsed command-line arguments from cli(). summary: Summary output format.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright init [OPTIONS]

Options

--summary <summary>¶

Show project summary after initialisation in the chosen format.

Options:: table | json

decide¶

Suggest a version bump without modifying files.

bumpwright decide¶

Suggest a version bump without modifying files.

bumpwright decide [OPTIONS]

Options

--base <base>¶: Base git reference when auto-deciding the level. Defaults to the last release commit or the previous commit (HEAD^).

--head <head>¶

Head git reference.

Default:: 'HEAD'

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--emit-changelog¶: Print expected changelog for the suggested version.

--explain¶: Show reasoning behind the selected bump level.

--no-impl-change-patch¶: Ignore implementation-only changes to public symbols.

--repo-url <repo_url>¶: Base repository URL for linking commit hashes in Markdown output. Can also be set via [changelog].repo_url in configuration.

--changelog-template <changelog_template>¶: Jinja2 template file for changelog entries; defaults to the built-in template or [changelog].template when configured.

--changelog-exclude <changelog_exclude>¶: Regex pattern for commit subjects to exclude from changelog (repeatable).

--enable-analyser <enable_analyser>¶: Enable analyser NAME (repeatable) in addition to configuration.

--disable-analyser <disable_analyser>¶: Disable analyser NAME (repeatable) even if configured.

bump¶

Apply the suggested version and update files.

bumpwright bump¶

Update version metadata and optionally commit and tag the change.

Args:: args: Parsed command-line arguments from cli(). **kwargs: Command-specific options. Notable parameters include:

base (str | None): Git reference used as the comparison base when inferring the bump level. Defaults to the latest release commit or HEAD^.

head (str): Git reference representing the working tree. Defaults to HEAD.

output_fmt (str): Output format: text (default), md for Markdown, or json for machine-readable output.

repo_url (str | None): Base repository URL used to build commit links in Markdown output. Overrides [changelog].repo_url when provided.

decide (bool): When True, only report the bump level without modifying any files.

enable_analyser (tuple[str, …]): Names of analysers to enable in addition to those configured.

disable_analyser (tuple[str, …]): Names of analysers to disable even if configured.

no_impl_change_patch (bool): When True, ignore implementation-only changes to public symbols when determining the bump level.

pyproject (str): Path to pyproject.toml. Defaults to pyproject.toml.

version_path (tuple[str, …]): Extra glob patterns for files whose version fields should be updated. Defaults include pyproject.toml, setup.py, setup.cfg, and any __init__.py, version.py, or _version.py files.

version_ignore (tuple[str, …]): Glob patterns for paths to exclude from version updates.

commit (bool): Create a git commit containing the version change.

tag (bool): Create a git tag for the new version.

dry_run (bool): Show the new version without modifying files.

changelog (str | None): Write release notes to the given file or stdout when - is provided.

changelog_template (str | None): Path to a Jinja2 template used to render changelog entries. Defaults to the built-in template.

changelog_exclude (tuple[str, …]): Regex patterns of commit subjects to omit from changelog entries.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright bump [OPTIONS]

Options

--base <base>¶: Base git reference when auto-deciding the level. Defaults to the last release commit or the previous commit (HEAD^).

--head <head>¶

Head git reference.

Default:: 'HEAD'

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--repo-url <repo_url>¶: Base repository URL for linking commit hashes in Markdown output. Can also be set via [changelog].repo_url in configuration.

--explain¶: Show reasoning behind the selected bump level.

--no-impl-change-patch¶: Ignore implementation-only changes to public symbols.

--enable-analyser <enable_analyser>¶: Enable analyser NAME (repeatable) in addition to configuration.

--disable-analyser <disable_analyser>¶: Disable analyser NAME (repeatable) even if configured.

--pyproject <pyproject>¶

Path to the project’s pyproject.toml file.

Default:: 'pyproject.toml'

--version-path <version_path>¶: Additional glob pattern for files containing the project version (repeatable). Defaults include pyproject.toml, setup.py, setup.cfg, and any __init__.py, version.py, or _version.py files.

--version-ignore <version_ignore>¶: Glob pattern for paths to exclude from version updates (repeatable).

--commit¶: Create a git commit for the version change.

--tag¶: Create a git tag for the new version.

--dry-run¶: Display the new version without modifying any files.

--changelog <FILE>¶: Append release notes to FILE or stdout when no path is given. Defaults to [changelog].path in configuration when omitted.

--changelog-template <changelog_template>¶: Jinja2 template file for changelog entries; defaults to the built-in template or [changelog].template when configured.

--changelog-exclude <changelog_exclude>¶: Regex pattern for commit subjects to exclude from changelog (repeatable). Combined with patterns from [changelog].exclude.

history¶

List previous bumps or roll back a release.

bumpwright history¶

List existing git tags, roll back a release, or purge bumpwright state.

Args:: args: Parsed command-line arguments from cli(). output_fmt: Desired output format. stats: Whether to include diff statistics between tags. rollback: Tag to remove and restore to the previous commit. purge: Remove all bumpwright release tags and reset versioned files.
Returns:: Exit status code, where 0 indicates success and 1 an error.

bumpwright history [OPTIONS]

Options

--format <output_fmt>¶

Output style: plain text, Markdown, or machine-readable JSON.

Default:: 'text'
Options:: text | md | json

--local-time¶: Display commit dates in local time instead of ISO-8601.

--stats¶: Include line change statistics between successive tags.

--rollback <TAG>¶: Delete TAG and restore versioned files to the previous commit.

--purge¶: Remove all bumpwright release tags and commits, restoring versioned files.