tbump: Bump Software Releases

Common errors

• Invalid config: Key 'file' error using pyproject.toml

  cause The `pyproject.toml` configuration for `tbump` is malformed, or the specific `[[tool.tbump.file]]` section for Poetry projects (introduced as a breaking change in v6.4.0) is missing.
  fix Ensure correct TOML syntax. For Poetry projects, add an explicit `[[tool.tbump.file]]` entry for `pyproject.toml` similar to: `[[tool.tbump.file]] src = "pyproject.toml" search = 'version = "{current_version}"'`.

• error: src refspec refs/tags/vX.Y.Z does not match any error: failed to push some refs to 'origin'

  cause This error typically indicates that `git push --atomic` failed, most likely because your Git client or remote repository does not support atomic pushes, which became default in tbump 6.5.
  fix In your `tbump.toml` file, add `atomic_push = false` under the `[git]` section to disable atomic pushes and use separate pushes for the branch and tag.

• tbump: error: No match for current version '1.2.3' in file 'src/my_module/__init__.py'

  cause The `search` string defined in `tbump.toml` for the specified file does not match the actual content of the file, or the `current` version in `tbump.toml` does not match what's in the file according to the `regex`.
  fix Verify that `[version].current` matches the actual version in your files, and that the `regex` correctly extracts it. Also, check that the `[[file]].search` pattern exactly matches the line containing the version in the target file, ensuring correct templating with `{current_version}`.

Warnings

• breaking As of v6.4.0, if using `tbump` with `pyproject.toml` for a Poetry project, the `version` key in `[tool.poetry]` is no longer implicitly bumped. You must explicitly configure it in `tbump.toml` or `[tool.tbump]` to be included in the version bump process.
  Fix: Add a `[[tool.tbump.file]]` section to your `pyproject.toml` (or `tbump.toml`) explicitly targeting the Poetry version key: `[[tool.tbump.file]] src = "pyproject.toml" search = 'version = "{current_version}"'`
• gotcha tbump defaults to using `git push --atomic`, which may not be supported by all Git versions or hosting providers. If you encounter push errors, this is a likely cause.
  Fix: Set `atomic_push = false` in the `[git]` section of your `tbump.toml` to revert to separate branch and tag pushes.
• breaking Support for Python 3.6 was dropped in version 6.7.0. Users on older Python versions will need to upgrade their Python environment to use newer tbump releases.
  Fix: Upgrade your Python environment to Python 3.7 or newer.
• gotcha The regular expression defined in `[version].regex` and the `search` patterns in `[[file]]` sections are critical and can be complex. Incorrect regex or search strings can lead to `tbump` failing to find or replace the version.
  Fix: Carefully test your `regex` and `search` patterns. Use named groups in your `regex` (e.g., `(?P<major>\d+)`) and ensure `current_version` is correctly templated in `search` strings. Run `tbump --dry-run <new_version>` to preview changes.
• gotcha By default, `tbump` is interactive and prompts for confirmation before performing Git actions. This can halt automation in CI/CD pipelines.
  Fix: Use the `--non-interactive` flag when running `tbump` in automated environments, e.g., `tbump --non-interactive <new_version>`.

Install

• pip install tbump Install via pip
• pipx install tbump Install via pipx (recommended)

Quickstart

To use tbump, you typically create a `tbump.toml` configuration file in your project's root directory, or embed the configuration in `pyproject.toml` under the `[tool.tbump]` section. This configuration specifies the current version, a regex to match it, Git commit/tag templates, and the files where the version string should be updated. After configuration, run `tbump <new_version>` from your project's root.

import os

# Create a dummy project structure for demonstration
os.makedirs('my_project', exist_ok=True)
with open('my_project/pyproject.toml', 'w') as f:
    f.write('current = "1.2.3"\n')
    f.write('[tool.poetry]\n')
    f.write('name = "my_project"\n')
    f.write('version = "1.2.3"\n')

with open('my_project/src/__init__.py', 'w') as f:
    f.write('__version__ = "1.2.3"\n')

# --- tbump configuration (tbump.toml in the project root) ---
config_content = '''
[version]
current = "1.2.3"
regex = """(?P<major>\d+)\\.(?P<minor>\d+)\\.(?P<patch>\d+)"""

[git]
message_template = "Bump to {new_version}"
tag_template = "v{new_version}"

[[file]]
src = "pyproject.toml"
search = 'version = "{current_version}"'

[[file]]
src = "src/__init__.py"
search = '__version__ = "{current_version}"'
'''

with open('my_project/tbump.toml', 'w') as f:
    f.write(config_content)

print("Project setup in 'my_project/' with tbump.toml")
print("To bump the version, navigate to 'my_project/' and run:")
print("  git init")
print("  git add .")
print("  git commit -m \"Initial commit\"")
print("  tbump 1.2.4") # This will perform the bump and Git operations