{"library":"dunamai","title":"Dunamai: Dynamic Version Generation","description":"Dunamai is a Python 3.5+ library and command-line tool for producing dynamic, standards-compliant version strings, derived from tags in your version control system (Git, Mercurial, Darcs, Subversion, Bazaar, Fossil, Pijul). It facilitates uniquely identifying nightly or per-commit builds in continuous integration and simplifying releases by creating a tag. It supports various version styles like PEP 440 and Semantic Versioning, or custom formats. Dunamai, currently at version 1.26.1, maintains an active development and release cadence.","status":"active","version":"1.26.1","language":"en","source_language":"en","source_url":"https://github.com/mtkennerly/dunamai","tags":["versioning","scm","git","mercurial","pijul","darcs","breezy","ci","release","automation"],"install":[{"cmd":"pip install dunamai","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Version","correct":"from dunamai import Version"},{"symbol":"Style","correct":"from dunamai import Style"},{"note":"Used for predefined version tag patterns.","symbol":"Pattern","correct":"from dunamai import Pattern"}],"quickstart":{"code":"import os\nfrom dunamai import Version\n\n# In a Git repository with tag v0.1.0 and some commits after it\ntry:\n    version = Version.from_any_vcs(\n        # Optional: Specify a fallback version if no VCS is found or no tags match.\n        # Defaults to '0.0.0' if not strict, or raises an error if strict.\n        fallback=os.environ.get(\"DUNAMAI_FALLBACK_VERSION\", \"0.0.0\"),\n        # Optional: Set strict=True to raise an error if a version cannot be determined.\n        # Default is False, which may use fallback.\n        strict=bool(os.environ.get(\"DUNAMAI_STRICT\", \"\").lower() == \"true\"),\n    )\n    # Prints a PEP 440 compliant version like \"0.1.0.post7.dev0+g29045e8\"\n    print(f\"Current version: {version.serialize()}\")\n    # Or a Semantic Versioning compliant string like \"0.1.0-post.7\"\n    print(f\"Semantic version: {version.serialize(style='semver', metadata=False)}\")\nexcept RuntimeError as e:\n    print(f\"Could not determine version: {e}\")\n    # Handle cases where version cannot be determined (e.g., not in a VCS repo)\n","lang":"python","description":"This example demonstrates how to retrieve and serialize a dynamic version string from any detected VCS. It includes options for fallback versions and strict mode, which are crucial for robust integration in varied environments like CI/CD pipelines. The output can be formatted according to different versioning styles."},"warnings":[{"fix":"Upgrade to `dunamai` v1.23.1 or newer to ensure correct version comparison behavior.","message":"The `Version.__lt__` comparison logic was fixed in v1.23.1. Prior to this, `Version.__lt__` incorrectly checked if *all* fields were less, rather than using proper field precedence for version ordering. This could lead to incorrect comparisons between `Version` instances.","severity":"breaking","affected_versions":"<1.23.1"},{"fix":"Ensure your CI environment performs a full clone. For GitHub Actions, use `actions/checkout@v3` with `fetch-depth: 0`. For GitLab, set `GIT_DEPTH` to `0`.","message":"Dunamai requires access to the full version history to accurately find tags and compute distance. CI systems often perform shallow clones by default, which can prevent Dunamai from determining the correct version.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `dunamai` v1.23.2 or newer, which includes a fix for this issue. Alternatively, ensure `GIT_TRACE` is not set when running `dunamai`.","message":"Setting the `GIT_TRACE` environment variable can cause `Version.from_git` to fail due to unexpected output from Git commands.","severity":"gotcha","affected_versions":"<1.23.2"},{"fix":"Upgrade to `dunamai` v1.26.1 or newer to correctly utilize the `highest_tag` functionality.","message":"The `highest_tag` argument, intended to select the numerically highest version tag, was ignored in `Version.from_any_vcs()` and related functions.","severity":"gotcha","affected_versions":"1.26.0"},{"fix":"Prefer annotated tags (`git tag -a`) over lightweight tags. Avoid tagging the initial empty commit (created with `--allow-empty`).","message":"Using lightweight Git tags (instead of annotated tags) or having an initial commit that is both tagged and empty can lead to unreliable tag detection and sorting, as Git does not store creation times for lightweight tags and has reporting issues with empty, tagged initial commits.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}