gitcalver 20260418.5__tar.gz

gitcalver-20260418.5/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+          cache-suffix: ${{ matrix.python-version }}
+      - run: uv python install ${{ matrix.python-version }}
+      - run: make test
+        env:
+          UV_PYTHON: ${{ matrix.python-version }}
+
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - run: uv python install 3.14
+      - run: make lint
+
+  build:
+    name: Build distribution
+    needs: [test, lint]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+      - run: uv python install 3.14
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gitcalver
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1

gitcalver-20260418.5/.gitignore

@@ -0,0 +1,10 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+__pycache__/
+*.egg-info/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/

gitcalver-20260418.5/.ruff.toml

@@ -0,0 +1,41 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+# Match requires-python: support all non-EOL Python versions.
+target-version = "py310"
+
+[lint]
+select = [
+  "ALL",
+]
+
+ignore = [
+  "ANN401",  # typing.Any
+  "C90",     # Cyclomatic complexity
+  "D",       # pydocstyle (disable docstring rules)
+  "PLR09",   # "Too many" branches, arguments, etc.
+  "S603",    # subprocess output
+  "S607",    # subprocess using path
+  "RUF001",  # ambiguous Unicode character in string
+  "RUF002",  # ambiguous Unicode character in docstring
+  "RUF003",  # ambiguous Unicode character in comment
+  "A002",    # shadowing builtins (dir, format) -- intentional API design
+  "COM812",  # trailing comma -- conflicts with formatter
+  "FBT",     # boolean arguments -- acceptable for internal functions
+]
+
+[lint.per-file-ignores]
+"src/gitcalver/_hatch_hooks.py" = [
+  "PLC0415", # import not at top level -- lazy import for plugin registration
+]
+"src/gitcalver/cli.py" = [
+  "T201",     # print() -- CLI entry point
+]
+"tests/**" = [
+  "S101",     # assert
+  "PLR2004",  # magic values
+  "INP001",   # implicit namespace package (tests/ is intentionally not a package)
+]
+
+[lint.isort]
+known-local-folder = ["_helpers"]

gitcalver-20260418.5/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.

gitcalver-20260418.5/Makefile

@@ -0,0 +1,15 @@
+.PHONY: sync test lint fmt
+
+sync:
+	uv sync --frozen
+
+test: sync
+	uv run pytest
+
+lint: sync
+	uv run ruff check
+	uv run ruff format --check
+	uv run ty check
+
+fmt: sync
+	uv run ruff format

gitcalver-20260418.5/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,155 @@
+# 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/pyproject.toml

@@ -0,0 +1,59 @@
+# Copyright © 2026 Michael Shields
+# SPDX-License-Identifier: MIT
+
+[project]
+name = "gitcalver"
+dynamic = ["version"]
+description = "Deterministic calendar versioning from git history"
+# Support all non-EOL Python versions.
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [
+    {name = "Michael Shields", email = "shields@gitcalver.org"},
+]
+keywords = ["versioning", "calver", "git", "calendar-versioning"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.urls]
+Homepage = "https://gitcalver.org"
+Source = "https://github.com/gitcalver/python"
+Issues = "https://github.com/gitcalver/python/issues"
+
+[project.scripts]
+gitcalver = "gitcalver.cli:main"
+
+[project.entry-points.hatch]
+gitcalver = "gitcalver._hatch_hooks"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "code"
+path = "src/gitcalver/__init__.py"
+expression = "get_version(dirty='+dirty')"
+search-paths = ["src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitcalver"]
+
+[dependency-groups]
+dev = [
+    "hatchling>=1.1.0",
+    "pytest>=8",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.11",
+    "ty>=0.0.1a7",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gitcalver-20260418.5/src/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-20260418.5/src/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-20260418.5/src/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-20260418.5/src/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