Examples¶

This section contains runnable code examples that demonstrate real-world usage of GitVersioned. Each example is self-contained and can be copied directly into your own project.

[!NOTE] All examples assume you have completed Installation.

Example Index¶

Below is a curated list of available examples, categorized by build tool and use case:

Hatchling Examples¶

Example	Complexity	Description
Hatchling Root Example	Beginner	Standard Hatchling configuration using `pyproject.toml` and `[tool.hatch.version]`.
Hatchling Docker Overrides	Intermediate	Dynamic versioning featuring external `Dockerfile` overrides during build.
Hatchling Custom Configuration	Intermediate	Dynamic versioning showcasing custom pre-release templates and auto-increment strategies.

Setuptools Examples¶

Example	Complexity	Description
Setuptools Root Example	Beginner	Standard Setuptools configuration using `pyproject.toml` and `[tool.gitversioned]`.
Setuptools Configuration via setup.cfg	Beginner	Standard Setuptools configuration using a legacy `setup.cfg` file.
Setuptools Configuration via setup.py	Beginner	Standard Setuptools configuration using a traditional legacy `setup.py` file.
Setuptools Configuration with Dockerfile Overrides	Intermediate	Setuptools integration with external `Dockerfile` overrides via `pyproject.toml`.
Setuptools Custom Configuration	Intermediate	Custom Setuptools config overrides featuring customized dirty ignoral rules and templates.

Maturin Examples¶

Example	Complexity	Description
Maturin Root Example	Beginner	Minimal Rust/Python polyglot extension using Maturin and `gitversioned.plugins.maturin_plugin`.
Maturin Polyglot Configuration with Overrides	Advanced	Maturin build backend integration with multi-target overrides (`Cargo.toml` and `Dockerfile`).
Maturin Custom Configuration	Intermediate	Maturin configuration specifying custom tag formatting and Rust-specific settings.

General (CLI & API) Examples¶

Example	Complexity	Description
General Web App (CI/CD) Example	Beginner	Python web app serving its dynamic Git-resolved version from an endpoint.
Docker Build Argument Injection	Beginner	Sourcing and formatting dynamic versions to inject as Docker container build arguments.
In-place File Update via Regex	Beginner	Direct, in-place version string replacement in non-python files using regex patterns.
Programmatic API Usage	Beginner	Programmatic version resolution and output writing using the public python package API.
Programmatic Custom Configuration	Intermediate	Programmatic API usage applying custom dirty checks, formats, and auto-increment.

Contributing an Example

Have a useful snippet or pattern to share? See the Contributing Guide to learn how to add a new example to this section.