gitcalver 20260418.5__py3-none-any.whl

gitcalver/__init__.py

@@ -0,0 +1,50 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from gitcalver._errors import EXIT_DIRTY, EXIT_ERROR, EXIT_WRONG_BRANCH, ExitError
+from gitcalver._format import Format
+from gitcalver._version import forward, reverse
+
+
+def get_version(
+    *,
+    revision: str | None = None,
+    prefix: str = "",
+    dirty: str = "",
+    dirty_hash: bool = True,
+    branch: str | None = None,
+    repo: str | None = None,
+) -> str:
+    fmt = Format(prefix=prefix, dirty_suffix=dirty or None, dirty_hash=dirty_hash)
+    return forward(
+        dir=repo,
+        revision=revision,
+        fmt=fmt,
+        branch_override=branch or None,
+    )
+
+
+def find_commit(
+    version: str,
+    *,
+    prefix: str = "",
+    branch: str | None = None,
+    repo: str | None = None,
+    short: bool = False,
+) -> str:
+    return reverse(
+        dir=repo,
+        version_str=version.removeprefix(prefix),
+        branch_override=branch or None,
+        short=short,
+    )
+
+
+__all__ = [
+    "EXIT_DIRTY",
+    "EXIT_ERROR",
+    "EXIT_WRONG_BRANCH",
+    "ExitError",
+    "find_commit",
+    "get_version",
+]

gitcalver/__main__.py

@@ -0,0 +1,7 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from gitcalver.cli import main
+
+if __name__ == "__main__":
+    main()

gitcalver/_branch.py

@@ -0,0 +1,59 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from gitcalver import _git
+from gitcalver._errors import ExitError
+
+
+def detect_branch(
+    dir: str | None = None, override: str | None = None
+) -> tuple[str, str]:
+    if override is not None:
+        if "/" in override:
+            candidates = [override]
+        else:
+            candidates = [
+                f"refs/remotes/origin/{override}",
+                f"refs/heads/{override}",
+            ]
+        for ref in candidates:
+            hash_ = _git.try_ref_hash(ref, dir=dir)
+            if hash_ is not None:
+                name = override.rsplit("/", 1)[-1]
+                return name, hash_
+        msg = f"branch not found: {override}"
+        raise ExitError(msg)
+
+    target = _git.symbolic_ref("refs/remotes/origin/HEAD", dir=dir)
+    if target:
+        hash_ = _git.try_ref_hash(target, dir=dir)
+        if hash_ is not None:
+            name = target.removeprefix("refs/remotes/origin/")
+            return name, hash_
+
+    for name in ("main", "master"):
+        hash_ = _git.try_ref_hash(f"refs/remotes/origin/{name}", dir=dir)
+        if hash_ is not None:
+            return name, hash_
+
+    for name in ("main", "master"):
+        hash_ = _git.try_ref_hash(f"refs/heads/{name}", dir=dir)
+        if hash_ is not None:
+            return name, hash_
+
+    msg = "cannot determine default branch"
+    raise ExitError(msg)
+
+
+def is_on_branch(
+    target_hash: str,
+    branch_hash: str,
+    dir: str | None = None,
+) -> bool:
+    # Optimization: git treats a commit as its own ancestor, so the
+    # is_ancestor call below would handle this case correctly, but
+    # this avoids spawning git for the common same-hash case.
+    if target_hash == branch_hash:
+        return True
+
+    return _git.is_ancestor(target_hash, branch_hash, dir=dir)

gitcalver/_errors.py

@@ -0,0 +1,13 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+EXIT_ERROR = 1
+EXIT_DIRTY = 2
+EXIT_WRONG_BRANCH = 3
+
+
+class ExitError(Exception):
+    def __init__(self, message: str, code: int = EXIT_ERROR) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message

gitcalver/_format.py

@@ -0,0 +1,24 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Format:
+    prefix: str
+    # None means dirty workspaces are not allowed; otherwise the string
+    # is appended to versions built from a dirty workspace.
+    dirty_suffix: str | None
+    dirty_hash: bool
+
+
+def format_version(
+    fmt: Format, date: str, count: int, dirty: bool, short_hash: str
+) -> str:
+    version = f"{fmt.prefix}{date}.{count}"
+    if dirty and fmt.dirty_suffix is not None:
+        version += fmt.dirty_suffix
+        if fmt.dirty_hash:
+            version += f".{short_hash}"
+    return version

gitcalver/_git.py

@@ -0,0 +1,130 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+import os
+import subprocess
+from collections.abc import Generator
+
+
+class GitError(Exception):
+    pass
+
+
+_SHORT_HASH_LEN = 7
+
+
+def _os_error_message(e: OSError) -> str:
+    if e.filename == "git":
+        return "git not found on PATH"
+    return str(e)
+
+
+def _run(*args: str, dir: str | None = None) -> subprocess.CompletedProcess[str]:
+    try:
+        return subprocess.run(
+            ["git", *args],
+            capture_output=True,
+            text=True,
+            cwd=dir,
+            check=False,
+        )
+    except OSError as e:
+        raise GitError(_os_error_message(e)) from e
+
+
+def git(*args: str, dir: str | None = None) -> str:
+    result = _run(*args, dir=dir)
+    if result.returncode != 0:
+        raise GitError(result.stderr.strip())
+    return result.stdout.strip()
+
+
+def git_ok(*args: str, dir: str | None = None) -> bool:
+    return _run(*args, dir=dir).returncode == 0
+
+
+def rev_parse(rev: str, dir: str | None = None) -> str:
+    return git("rev-parse", rev, dir=dir)
+
+
+def rev_parse_short(rev: str, dir: str | None = None) -> str:
+    # Pin the minimum length so output doesn't vary with core.abbrev.
+    return git("rev-parse", f"--short={_SHORT_HASH_LEN}", rev, dir=dir)
+
+
+def is_git_repo(dir: str | None = None) -> bool:
+    return git_ok("rev-parse", "--git-dir", dir=dir)
+
+
+def is_shallow(dir: str | None = None) -> bool:
+    return git("rev-parse", "--is-shallow-repository", dir=dir) == "true"
+
+
+def has_commits(dir: str | None = None) -> bool:
+    return git_ok("rev-parse", "--verify", "HEAD", dir=dir)
+
+
+def is_dirty(dir: str | None = None) -> bool:
+    try:
+        return git("status", "--porcelain", dir=dir) != ""
+    except GitError:
+        return False
+
+
+def symbolic_ref(ref: str, dir: str | None = None) -> str | None:
+    try:
+        return git("symbolic-ref", ref, dir=dir)
+    except GitError:
+        return None
+
+
+def try_ref_hash(ref: str, dir: str | None = None) -> str | None:
+    try:
+        return git("rev-parse", "--verify", ref, dir=dir)
+    except GitError:
+        return None
+
+
+def is_ancestor(commit: str, ancestor_of: str, dir: str | None = None) -> bool:
+    return git_ok("merge-base", "--is-ancestor", commit, ancestor_of, dir=dir)
+
+
+def merge_base(rev1: str, rev2: str, dir: str | None = None) -> str | None:
+    try:
+        return git("merge-base", rev1, rev2, dir=dir)
+    except GitError:
+        return None
+
+
+def first_parent_log(
+    rev: str, dir: str | None = None
+) -> Generator[tuple[str, str], None, None]:
+    env = {**os.environ, "TZ": "UTC"}
+    try:
+        proc = subprocess.Popen(
+            [
+                "git",
+                "log",
+                rev,
+                "--first-parent",
+                "--format=%H %cd",
+                "--date=format-local:%Y%m%d",
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
+            text=True,
+            cwd=dir,
+            env=env,
+        )
+    except OSError as e:
+        raise GitError(_os_error_message(e)) from e
+    with proc:
+        if proc.stdout is None:
+            return
+        for line in proc.stdout:
+            hash_, _, date = line.strip().partition(" ")
+            if date:
+                yield hash_, date
+        if proc.wait() != 0:
+            msg = f"git log {rev} failed"
+            raise GitError(msg)

gitcalver/_hatch_hooks.py

@@ -0,0 +1,18 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from hatchling.plugin import hookimpl
+
+if TYPE_CHECKING:
+    from hatchling.version.source.plugin.interface import VersionSourceInterface
+
+
+@hookimpl
+def hatch_register_version_source() -> type[VersionSourceInterface]:
+    from gitcalver._hatch_source import GitCalverSource
+
+    return GitCalverSource

gitcalver/_hatch_source.py

@@ -0,0 +1,28 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+from hatchling.version.source.plugin.interface import VersionSourceInterface
+
+from gitcalver import ExitError, get_version
+
+
+class GitCalverSource(VersionSourceInterface):
+    PLUGIN_NAME = "gitcalver"
+
+    def get_version_data(self) -> dict[str, str]:
+        config = self.config
+        if config.get("no-dirty-hash", False) and not config.get("dirty", ""):
+            msg = "gitcalver: no-dirty-hash requires dirty"
+            raise RuntimeError(msg)
+        try:
+            version = get_version(
+                prefix=str(config.get("prefix", "")),
+                dirty=str(config.get("dirty", "")),
+                dirty_hash=not config.get("no-dirty-hash", False),
+                branch=config.get("branch") or None,
+                repo=self.root,
+            )
+        except ExitError as e:
+            msg = f"gitcalver: {e.message}"
+            raise RuntimeError(msg) from e
+        return {"version": version}

gitcalver/_version.py

@@ -0,0 +1,183 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+import contextlib
+import datetime
+import re
+
+from gitcalver import _git
+from gitcalver._branch import detect_branch, is_on_branch
+from gitcalver._errors import EXIT_DIRTY, EXIT_WRONG_BRANCH, ExitError
+from gitcalver._format import Format, format_version
+
+VERSION_RE = re.compile(r"^(\d{8})\.([1-9]\d*)$")
+
+
+def is_version_string(s: str) -> bool:
+    return VERSION_RE.match(s) is not None
+
+
+def _date_went_backwards(older: str, newer: str) -> ExitError:
+    msg = (
+        f"committer date not monotonic: "
+        f"older commit dated {older} has a later date than "
+        f"newer commit dated {newer}"
+    )
+    return ExitError(msg)
+
+
+def _validate_repo(dir: str | None) -> None:
+    try:
+        is_repo = _git.is_git_repo(dir=dir)
+    except _git.GitError as e:
+        msg = str(e)
+        raise ExitError(msg) from e
+    if not is_repo:
+        msg = "not a git repository"
+        raise ExitError(msg)
+    try:
+        shallow = _git.is_shallow(dir=dir)
+    except _git.GitError as e:
+        msg = f"cannot determine repository state: {e}"
+        raise ExitError(msg) from e
+    if shallow:
+        msg = (
+            "shallow clone detected; full history is required"
+            " (use git fetch --unshallow)"
+        )
+        raise ExitError(msg)
+    if not _git.has_commits(dir=dir):
+        msg = "no commits in repository"
+        raise ExitError(msg)
+
+
+def forward(
+    *,
+    dir: str | None,
+    revision: str | None,
+    fmt: Format,
+    branch_override: str | None,
+) -> str:
+    _validate_repo(dir)
+
+    is_head = revision is None
+    rev_spec = f"{'HEAD' if is_head else revision}^{{commit}}"
+    try:
+        target_hash = _git.rev_parse(rev_spec, dir=dir)
+    except _git.GitError:
+        msg = (
+            "no commits in repository"
+            if is_head
+            else f"not a gitcalver version or git revision: {revision}"
+        )
+        raise ExitError(msg) from None
+
+    branch_name, branch_hash = detect_branch(dir=dir, override=branch_override)
+
+    version_rev = target_hash
+    off_branch = False
+
+    if not is_on_branch(target_hash, branch_hash, dir=dir):
+        if not is_head:
+            msg = f"{revision} is not on the default branch ({branch_name})"
+            raise ExitError(msg, EXIT_WRONG_BRANCH)
+        mb = _git.merge_base(target_hash, branch_hash, dir=dir)
+        if mb is None:
+            msg = f"HEAD is not traceable to the default branch ({branch_name})"
+            raise ExitError(msg, EXIT_WRONG_BRANCH)
+        off_branch = True
+        version_rev = mb
+
+    dirty = False
+    if off_branch or (is_head and _git.is_dirty(dir=dir)):
+        if fmt.dirty_suffix is None:
+            if off_branch:
+                msg = (
+                    f"HEAD is off the default branch ({branch_name});"
+                    " use --dirty to produce a divergent version"
+                )
+            else:
+                msg = "workspace is dirty; use --dirty to allow"
+            raise ExitError(msg, EXIT_DIRTY)
+        dirty = True
+
+    date, count = walk_first_parent(dir=dir, rev=version_rev)
+
+    short_hash = ""
+    if dirty and fmt.dirty_hash:
+        short_hash = _git.rev_parse_short(target_hash, dir=dir)
+
+    return format_version(fmt, date, count, dirty, short_hash)
+
+
+def walk_first_parent(*, dir: str | None, rev: str) -> tuple[str, int]:
+    with contextlib.closing(_git.first_parent_log(rev, dir=dir)) as entries:
+        first = next(entries, None)
+        if first is None:
+            msg = "no commits found"
+            raise ExitError(msg)
+        date = first[1]
+        count = 1
+
+        # Only the first date transition matters: once the date changes,
+        # we're done counting. Monotonicity is only checked within the
+        # target date's run; earlier violations are not surfaced here.
+        for _, entry_date in entries:
+            if entry_date != date:
+                if entry_date > date:
+                    raise _date_went_backwards(entry_date, date)
+                break
+            count += 1
+
+    return date, count
+
+
+def reverse(
+    *,
+    dir: str | None,
+    version_str: str,
+    branch_override: str | None,
+    short: bool,
+) -> str:
+    _validate_repo(dir)
+
+    match = VERSION_RE.match(version_str)
+    if not match:
+        msg = f"not a gitcalver version or git revision: {version_str}"
+        raise ExitError(msg)
+
+    date_str = match.group(1)
+    n = int(match.group(2))
+
+    try:
+        datetime.date(int(date_str[:4]), int(date_str[4:6]), int(date_str[6:8]))
+    except ValueError:
+        msg = f"invalid date in version: {version_str}"
+        raise ExitError(msg) from None
+
+    _, branch_hash = detect_branch(dir=dir, override=branch_override)
+
+    candidates: list[str] = []
+    # git log is newest-first; a later date on an older commit is non-monotonic.
+    newer_date: str | None = None
+    with contextlib.closing(_git.first_parent_log(branch_hash, dir=dir)) as entries:
+        for commit_hash, commit_date in entries:
+            if newer_date is not None and commit_date > newer_date:
+                raise _date_went_backwards(commit_date, newer_date)
+            newer_date = commit_date
+            if commit_date == date_str:
+                candidates.append(commit_hash)
+            elif commit_date < date_str:
+                # Dates are non-increasing (checked above); no earlier matches.
+                break
+
+    if n > len(candidates):
+        msg = f"version not found: {version_str}"
+        raise ExitError(msg)
+
+    # N=1 is oldest on that date; candidates are newest-first.
+    target_hash = candidates[-n]
+
+    if short:
+        return _git.rev_parse_short(target_hash, dir=dir)
+    return target_hash

gitcalver/cli.py

@@ -0,0 +1,178 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+import argparse
+import importlib.metadata
+import sys
+from dataclasses import dataclass
+from typing import NoReturn
+
+from gitcalver._errors import ExitError
+from gitcalver._format import Format
+from gitcalver._version import forward, is_version_string, reverse
+
+USAGE = """\
+Usage: gitcalver [options] [REVISION | VERSION]
+
+Compute a gitcalver version for a git commit, or find the commit for a version.
+
+Options:
+  --prefix PREFIX     Prepend PREFIX to the version (default: none)
+  --dirty STRING      Allow dirty workspace; append STRING.HASH as suffix
+  --no-dirty          Refuse dirty workspace (overrides --dirty)
+  --no-dirty-hash     Suppress .HASH in dirty suffix (requires --dirty)
+  --branch BRANCH     Override default branch detection
+  --short             Output short commit hash (reverse mode only)
+  --version           Show version and exit
+  --help              Show this help
+"""
+
+
+def _package_version() -> str:
+    try:
+        return importlib.metadata.version("gitcalver")
+    except importlib.metadata.PackageNotFoundError:
+        return "unknown"
+
+
+@dataclass
+class Args:
+    help: bool = False
+    version: bool = False
+    prefix: str = ""
+    dirty: str = ""
+    no_dirty: bool = False
+    no_dirty_hash: bool = False
+    branch: str | None = None
+    short: bool = False
+    positional: str | None = None
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        raise ExitError(message)
+
+
+class _NonEmptyStrAction(argparse.Action):
+    def __call__(
+        self,
+        parser: argparse.ArgumentParser,
+        namespace: argparse.Namespace,
+        values: object,
+        option_string: str | None = None,
+    ) -> None:
+        if not values:
+            parser.error(f"{option_string} requires a non-empty string")
+        setattr(namespace, self.dest, values)
+
+
+# Options that take a string value; used by `_normalize_argv` to rewrite the
+# space-separated form to `--opt=value` so argparse accepts values starting
+# with `-`. Keep in sync with the non-boolean options declared in `_parse_args`.
+_OPTS_TAKING_VALUE = frozenset({"--prefix", "--dirty", "--branch"})
+
+
+def _normalize_argv(argv: list[str]) -> list[str]:
+    """Rewrite `--opt value` to `--opt=value` for options in `_OPTS_TAKING_VALUE`.
+
+    argparse otherwise refuses values that begin with `-` in the space-separated
+    form (so `--dirty -dirty` fails, though `--dirty=-dirty` works). Rewriting
+    makes both forms equivalent. Stops at `--` so values after the terminator
+    are passed through unchanged.
+    """
+    result: list[str] = []
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--":
+            result.extend(argv[i:])
+            return result
+        if arg in _OPTS_TAKING_VALUE and i + 1 < len(argv):
+            result.append(f"{arg}={argv[i + 1]}")
+            i += 2
+        else:
+            result.append(arg)
+            i += 1
+    return result
+
+
+def _parse_args(argv: list[str]) -> Args:
+    parser = _Parser(prog="gitcalver", add_help=False, allow_abbrev=False)
+    parser.add_argument("--help", action="store_true")
+    parser.add_argument("--version", action="store_true")
+    parser.add_argument("--prefix", default="")
+    parser.add_argument("--dirty", action=_NonEmptyStrAction, default="")
+    parser.add_argument("--no-dirty", action="store_true")
+    parser.add_argument("--no-dirty-hash", action="store_true")
+    parser.add_argument("--branch", default=None)
+    parser.add_argument("--short", action="store_true")
+    parser.add_argument("positional", nargs="?", default=None)
+
+    args = parser.parse_args(_normalize_argv(argv), namespace=Args())
+
+    if args.no_dirty_hash and not args.dirty:
+        parser.error("--no-dirty-hash requires --dirty")
+
+    return args
+
+
+def _build_format(args: Args) -> Format:
+    dirty_suffix: str | None = None if args.no_dirty else (args.dirty or None)
+    return Format(
+        prefix=args.prefix,
+        dirty_suffix=dirty_suffix,
+        dirty_hash=not args.no_dirty_hash,
+    )
+
+
+def run(argv: list[str], *, dir: str | None = None) -> tuple[str, int]:
+    try:
+        args = _parse_args(argv)
+    except ExitError as e:
+        return f"gitcalver: {e.message}", e.code
+
+    if args.help:
+        return USAGE.rstrip("\n"), 0
+
+    if args.version:
+        return f"gitcalver {_package_version()}", 0
+
+    lookup: str | None = None
+    # Require the prefix to match before reverse-lookup; avoids treating a
+    # bare `20260410.1` as a version when --prefix is set.
+    if args.positional is not None and args.positional.startswith(args.prefix):
+        candidate = args.positional.removeprefix(args.prefix)
+        if is_version_string(candidate):
+            lookup = candidate
+
+    if args.short and lookup is None:
+        return "gitcalver: --short is only valid in reverse lookup mode", 1
+
+    try:
+        if lookup is not None:
+            result = reverse(
+                dir=dir,
+                version_str=lookup,
+                branch_override=args.branch,
+                short=args.short,
+            )
+        else:
+            fmt = _build_format(args)
+            result = forward(
+                dir=dir,
+                revision=args.positional,
+                fmt=fmt,
+                branch_override=args.branch,
+            )
+    except ExitError as e:
+        return f"gitcalver: {e.message}", e.code
+
+    return result, 0
+
+
+def main(argv: list[str] | None = None) -> NoReturn:
+    if argv is None:
+        argv = sys.argv[1:]
+    output, code = run(argv)
+    print(output, file=sys.stderr if code != 0 else sys.stdout)
+    sys.exit(code)

gitcalver-20260418.5.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: gitcalver
+Version: 20260418.5
+Summary: Deterministic calendar versioning from git history
+Project-URL: Homepage, https://gitcalver.org
+Project-URL: Source, https://github.com/gitcalver/python
+Project-URL: Issues, https://github.com/gitcalver/python/issues
+Author-email: Michael Shields <shields@gitcalver.org>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar-versioning,calver,git,versioning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# gitcalver
+
+A Python implementation of [GitCalVer](https://gitcalver.org), which derives
+calendar-based version numbers from git history.
+
+Each commit on the default branch gets a unique, strictly increasing version of
+the form `YYYYMMDD.N`, where `N` is the number of commits on that UTC date.
+
+See the [GitCalVer specification](https://gitcalver.org) for full details.
+
+## Installation
+
+```sh
+uv add gitcalver
+# or
+pip install gitcalver
+```
+
+See [Requirements](#requirements) below.
+
+## CLI usage
+
+```
+gitcalver [OPTIONS] [REVISION | VERSION]
+```
+
+With no arguments, prints the version for `HEAD`:
+
+```sh
+$ gitcalver
+20260411.3
+```
+
+Pass a revision to compute its version:
+
+```sh
+$ gitcalver HEAD~1
+20260411.2
+```
+
+### Version prefix
+
+Use `--prefix` to prepend a literal string:
+
+| Use case | Command                      | Example output   |
+|----------|------------------------------|------------------|
+| Default  | `gitcalver`                  | `20260411.3`     |
+| SemVer   | `gitcalver --prefix "0."`    | `0.20260411.3`   |
+| Go       | `gitcalver --prefix "v0."`   | `v0.20260411.3`  |
+
+### Dirty workspace
+
+By default, `gitcalver` exits with status 2 if the workspace has uncommitted
+changes. Use `--dirty STRING` to produce a version instead; the output will
+include the given string and a short commit hash
+(e.g. `--dirty "-dirty"` produces `20260411.3-dirty.abc1234`).
+
+Use `--no-dirty-hash` with `--dirty` to suppress the hash suffix.
+Use `--no-dirty` to explicitly refuse dirty versions (overrides `--dirty`).
+
+Dirty versions are a convenience and are not necessarily unique.
+
+### Reverse lookup
+
+Pass a version number to get the corresponding commit hash:
+
+```sh
+$ gitcalver 20260411.3
+a1b2c3d4e5f6...
+
+$ gitcalver --short --prefix "0." 0.20260411.3
+a1b2c3d
+```
+
+If the version was generated with `--prefix`, pass the same `--prefix` for
+reverse lookup. Dirty versions cannot be reversed.
+
+### Options
+
+| Option              | Description                                    |
+|---------------------|------------------------------------------------|
+| `--prefix PREFIX`   | Literal string prepended to version            |
+| `--dirty STRING`    | Enable dirty versions; append `STRING.HASH`    |
+| `--no-dirty`        | Refuse dirty versions (overrides `--dirty`)    |
+| `--no-dirty-hash`   | Suppress `.HASH` suffix (requires `--dirty`)   |
+| `--branch BRANCH`   | Base branch name; overrides auto-detection. This is the branch versions are minted on, not the branch you are working on. |
+| `--short`           | Output short commit hash (reverse lookup mode) |
+| `--help`            | Show help                                      |
+
+### Exit codes
+
+| Code | Meaning                                |
+|------|----------------------------------------|
+| 0    | Success                                |
+| 1    | Error (not a git repo, no commits, non-monotonic dates, shallow clone) |
+| 2    | Dirty workspace or off default branch (without `--dirty`) |
+| 3    | Cannot trace to default branch         |
+
+## Python API
+
+```python
+import gitcalver
+
+# Forward: compute a version for HEAD (or a specific revision).
+version = gitcalver.get_version(repo="/path/to/repo")
+# e.g. "20260411.3"
+
+version = gitcalver.get_version(
+    repo="/path/to/repo",
+    revision="HEAD~1",
+    prefix="v0.",
+    dirty="-dirty",
+)
+
+# Reverse: resolve a version back to a commit hash.
+commit = gitcalver.find_commit("20260411.3", repo="/path/to/repo")
+
+# If the version was generated with --prefix, pass the same prefix:
+commit = gitcalver.find_commit(
+    "v0.20260411.3", prefix="v0.", repo="/path/to/repo"
+)
+```
+
+Errors are raised as `gitcalver.ExitError`, which carries a `code` attribute
+matching the CLI exit codes above.
+
+## Hatch plugin
+
+`gitcalver` ships a [Hatch](https://hatch.pypa.io/) version source plugin. To
+use it in `pyproject.toml`:
+
+```toml
+[build-system]
+requires = ["hatchling", "gitcalver"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "gitcalver"
+# Optional:
+# prefix = "0."
+# dirty = "-dirty"
+# no-dirty-hash = true
+# branch = "main"
+```
+
+## Requirements
+
+- Python 3.10+
+- `git` on `$PATH`
+- Full commit history (shallow clones made with `--depth` are rejected; partial
+  clones made with `--filter=blob:none` are fine)
+
+## License
+
+MIT

gitcalver-20260418.5.dist-info/RECORD

@@ -0,0 +1,16 @@
+gitcalver/__init__.py,sha256=7896Q4BsaA7d2DdXCSvjrAfRd7LfuWvJfPNzhcZm7cY,1096
+gitcalver/__main__.py,sha256=8sjB1kMwKos_iow-KbnxPrfBUbZvZ7vH-EE4Zo6ct_k,138
+gitcalver/_branch.py,sha256=7GY1RFwF9nX9WpnduIILkTwIr2UjL2fyxRg4ENqo_74,1836
+gitcalver/_errors.py,sha256=6kB1YEdObCWsEtWR1EYtUG8r4wbNqZFHPbDPdh8ihEs,310
+gitcalver/_format.py,sha256=yJyq99VbM3dzCXXTXHWsNBQvv3ACiys9Fusc2uRhx4g,654
+gitcalver/_git.py,sha256=iZJhSDpZ9nX4p-3SOnBmos7XpFdznACQUaTzKrqxNF4,3395
+gitcalver/_hatch_hooks.py,sha256=Iz8jhG7a_NMYCujrFfor4pfRxv3uFDfkwgRTwLY9Up4,441
+gitcalver/_hatch_source.py,sha256=oclwg-P4aVEHL-7VA-2D_7mbV9SungeJ7O-Xs1adsAs,999
+gitcalver/_version.py,sha256=S9cY8XG5jGlzIBYBjWES-9a7QullpNiM7ezNEBSgXvE,5735
+gitcalver/cli.py,sha256=tpNNauoo6HlaILl_dejaFEZkEsNcZnfEE1daeBxBPOQ,5687
+gitcalver/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gitcalver-20260418.5.dist-info/METADATA,sha256=Qdg9lhDf0bVY2ZH-kQ_9dqekbZnJNO9ZXZkUi2DGlwI,5041
+gitcalver-20260418.5.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gitcalver-20260418.5.dist-info/entry_points.txt,sha256=IXcVpCaN0XiVcET1HWKbV_KGUsjFW9ecD77_YgFpju8,93
+gitcalver-20260418.5.dist-info/licenses/LICENSE,sha256=yMt4bLjW824Sn1DDZSbUz0K4TeJsl8jX4mVQfENnRe0,1058
+gitcalver-20260418.5.dist-info/RECORD,,

gitcalver-20260418.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

gitcalver-20260418.5.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+gitcalver = gitcalver.cli:main
+
+[hatch]
+gitcalver = gitcalver._hatch_hooks

gitcalver-20260418.5.dist-info/licenses/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2026 Michael Shields
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.