uv-workspace-dynamic-versioning

A powerful Hatch plugin for dynamic versioning and dependency injection in uv workspaces.

📖 Context & Origin

This project was created to address a specific limitation in the existing uv-dynamic-versioning plugin when used within complex monorepos and uv workspaces.

As discussed in ninoseki/uv-dynamic-versioning#81, the standard implementation often calculates version distance and commit hashes based on the entire repository history. In a workspace with multiple packages, this leads to:

1. False Positives: Packages bumping versions when unrelated code in the workspace changes.
2. Inaccurate Metadata: Commit hashes reflecting global repo state rather than the state of the specific package.

uv-workspace-dynamic-versioning introduces Directory-Specific Patching. It re-calculates the Git distance and commit hash by filtering the history to the specific package subdirectory, ensuring that versions only reflect changes relevant to that package.

🚀 Key Features

• VCS-Powered Versioning: Automatically derive versions from Git, Mercurial, and more via Dunamai.
• Workspace Aware: Accurate distance and commit hash calculation restricted to the project subdirectory.
• Dynamic Dependencies: Inject versions into dependencies using Jinja2 templates (e.g., pkg == {{ version.base }}).
• Secure by Design: Sandboxed Jinja2 environment and Path Traversal protection.
• Highly Configurable: Custom formats, bumping logic, and fallback versions.

🛠 Quick Start

1. Installation

Add the plugin to your build-system.requires in pyproject.toml:

[build-system]
requires = ["hatchling", "uv-workspace-dynamic-versioning"]
build-backend = "hatchling.build"

2. Basic Configuration

Enable the version source and mark the version as dynamic:

[project]
name = "my-awesome-package"
dynamic = ["version"]

[tool.hatch.version]
source = "uv-workspace-dynamic-versioning"

📚 Documentation

For full guides and API reference, visit our Documentation Site.

⚖️ License

Distributed under the terms of the MIT license.