# Usage

## Basic Setup

To enable dynamic versioning in your `hatch` project, configure your `pyproject.toml` as follows:

```toml
[project]
name = "my-package"
dynamic = ["version"]

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

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

## Workspace Versioning

When using this plugin within a `uv` workspace, it automatically detects changes specific to the directory where the `pyproject.toml` resides. 

If you have a tag `v0.1.0` and make a commit in `packages/pkg-a`, only `pkg-a`'s version will reflect the distance (e.g., `0.1.0.post1+g<hash>`), provided other packages in the workspace didn't change.

## Dynamic Dependencies

You can also use this plugin to dynamically set your project dependencies. This is useful for referencing other packages in the same workspace that share the same versioning scheme.

```toml
[project]
name = "my-package"
dynamic = ["version", "dependencies"]

[tool.hatch.metadata.hooks.uv-workspace-dynamic-versioning]
dependencies = [
    "other-pkg == {{ version.base }}",
    "requests >= 2.28.0"
]
```

In this example, `{{ version.base }}` will be replaced by the base version (e.g., `0.1.0`) generated by the version source.

## Version Bypassing

If you need to override the version manually (e.g., in CI), you can use the `UV_DYNAMIC_VERSIONING_BYPASS` environment variable:

```bash
export UV_DYNAMIC_VERSIONING_BYPASS=1.2.3
hatch build
```
