gitvars-render 0.1.0__py3-none-any.whl

gitvars/__init__.py

@@ -0,0 +1,10 @@
+"""Git provenance rendering with no runtime dependencies."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+try:
+    __version__ = version("gitvars-render")
+except PackageNotFoundError:
+    # A source checkout can be imported before the distribution is installed.
+    __version__ = "0+unknown"

gitvars/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

gitvars/cli.py

@@ -0,0 +1,126 @@
+"""Console commands; all user-facing output is sent to stdout."""
+
+import argparse
+from html import escape
+from pathlib import Path
+import sys
+
+from . import __version__
+from .config import load_config
+from .errors import GitvarsError
+from .files import (
+    Stats, absolute, atomic_write, copy_file, discover_entries, prepare_inputs,
+    prepare_output, validate_output,
+)
+from .git import collect_snapshot, require_clean_inputs
+from .render import Renderer, unified_diff
+
+
+class Parser(argparse.ArgumentParser):
+    def _print_message(self, message, file=None):
+        if message:
+            sys.stdout.write(message)
+
+
+def build_parser() -> Parser:
+    parser = Parser(prog="gitvars", description="Render Git provenance into selected UTF-8 files.")
+    parser.add_argument("--version", action="version", version=f"gitvars {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in ("render", "check"):
+        command = commands.add_parser(name, help="Render files" if name == "render" else "Check whether rendering would change files")
+        command.add_argument("paths", nargs="*", metavar="PATH", help="Files or directories (default: current directory)")
+        command.add_argument("--config", metavar="FILE")
+        command.add_argument("--prefix", metavar="PREFIX")
+        command.add_argument("--include", action="append", metavar="GLOB", help="Add a repository-relative rendering glob")
+        command.add_argument("--exclude", action="append", metavar="GLOB", help="Add a repository-relative exclusion glob")
+        command.add_argument("--exclude-regex", action="append", metavar="REGEX", help="Add a regex exclusion against repository-relative paths")
+        command.add_argument("--escape", action=argparse.BooleanOptionalAction, default=None, help="Recognize backslash escapes (default: enabled)")
+        command.add_argument("--html-escape", action="store_true", help="Escape inserted values for HTML text and quoted attributes")
+        verbosity = command.add_mutually_exclusive_group()
+        verbosity.add_argument("-v", "--verbose", action="store_true")
+        verbosity.add_argument("-q", "--quiet", action="store_true")
+        if name == "render":
+            command.add_argument("--dry-run", action="store_true", help="Print unified diffs without writing")
+            mode = command.add_mutually_exclusive_group()
+            mode.add_argument("--in-place", action="store_true", help="Replace clean tracked inputs (default)")
+            mode.add_argument("--output-dir", metavar="DIR", help="Copy files under DIR using repository-relative paths")
+            command.add_argument("-f", "--force", action="store_true", help="Clear a nonempty output directory; requires --output-dir")
+    return parser
+
+
+def run(args, stats: Stats) -> int:
+    output_arg = getattr(args, "output_dir", None)
+    force = getattr(args, "force", False)
+    if force and output_arg is None:
+        raise GitvarsError("-f/--force requires --output-dir; it cannot bypass clean-input checks")
+    config = load_config(Path.cwd(), args)
+    root, inputs = prepare_inputs(args.paths or ["."], config)
+    output = absolute(output_arg) if output_arg is not None else None
+    if output is not None:
+        validate_output(output, inputs, root, force)
+    entries = discover_entries(root, inputs, config, stats)
+    snapshot = collect_snapshot(root, config)
+    dry_run = getattr(args, "dry_run", False)
+    writing = args.command == "render" and not dry_run
+    if writing and output is None:
+        require_clean_inputs(snapshot, [entry.relative for entry in entries if entry.render])
+    if writing and output is not None:
+        prepare_output(output)
+    renderer = Renderer(config.prefix, config.escape)
+    for entry in entries:
+        stats.scanned += 1
+        destination = output / entry.relative if output else entry.source
+        if not entry.render:
+            stats.skipped += 1
+            if output is not None:
+                if writing:
+                    copy_file(entry.source, destination)
+                stats.copied += 1
+                if args.verbose:
+                    print(f"{'Would copy' if dry_run else 'Copied'} {entry.relative} unchanged")
+            continue
+        try:
+            original = entry.source.read_bytes()
+            text = original.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise GitvarsError(f"Selected file is not valid UTF-8: {entry.source}; adjust include/exclude patterns") from exc
+        values = snapshot.for_file(entry.relative)
+        if args.html_escape:
+            values = {name: escape(value) for name, value in values.items()}
+        rendered, unavailable = renderer.render(text, values)
+        changed = rendered != text
+        if changed:
+            stats.changed += 1
+        if args.verbose:
+            for name in sorted(unavailable):
+                print(f"Warning: {entry.relative}: {config.prefix}{name}__ is unavailable; using an empty string")
+            action = "Would render" if not writing else "Rendered"
+            print(f"{action} {entry.relative}" if changed else f"Unchanged {entry.relative}")
+        if dry_run and changed:
+            print(unified_diff(text, rendered, entry.relative, str(destination) if output else None), end="")
+        if writing:
+            if changed:
+                atomic_write(destination, rendered.encode("utf-8"), entry.source.stat().st_mode)
+            elif output is not None:
+                copy_file(entry.source, destination)
+        if output is not None:
+            stats.copied += 1
+    return 1 if args.command == "check" and stats.changed else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    stats = Stats()
+    try:
+        result = run(args, stats)
+    except (GitvarsError, OSError) as exc:
+        print(f"gitvars: error: {exc}")
+        stats.errors += 1
+        result = 2
+    if not args.quiet:
+        preview = "Dry run: " if getattr(args, "dry_run", False) else ""
+        print(
+            f"{preview}scanned {stats.scanned}; changed {stats.changed}; "
+            f"copied {stats.copied}; skipped {stats.skipped}; errors {stats.errors}"
+        )
+    return result

gitvars/config.py

@@ -0,0 +1,115 @@
+"""Configuration discovery and repository-relative file selection."""
+
+from dataclasses import dataclass
+from fnmatch import fnmatchcase
+from functools import cache
+from pathlib import Path
+import re
+import tomllib
+
+from .errors import GitvarsError
+
+
+@dataclass(frozen=True)
+class Config:
+    prefix: str = "__git_"
+    remote: str = "origin"
+    provider: str = "auto"
+    url_prefix: str | None = None
+    include: tuple[str, ...] = ()
+    exclude: tuple[str, ...] = ()
+    exclude_regex: tuple[str, ...] = ()
+    escape: bool = True
+
+
+def discover_config(cwd: Path) -> Path | None:
+    for directory in (cwd, *cwd.parents):
+        candidate = directory / ".gitvars"
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def load_config(cwd: Path, args) -> Config:
+    path = Path(args.config) if args.config else discover_config(cwd)
+    values = {}
+    if path is not None:
+        try:
+            with path.open("rb") as stream:
+                values = tomllib.load(stream)
+        except (OSError, tomllib.TOMLDecodeError) as exc:
+            raise GitvarsError(f"Cannot read configuration {path}: {exc}") from exc
+    unknown = values.keys() - Config.__dataclass_fields__.keys()
+    if unknown:
+        raise GitvarsError(f"Unknown configuration keys: {', '.join(sorted(unknown))}")
+    for key in ("prefix", "remote", "provider", "url_prefix"):
+        if key in values and (not isinstance(values[key], str) or not values[key]):
+            raise GitvarsError(f"Configuration '{key}' must be a nonempty string")
+    for key in ("include", "exclude", "exclude_regex"):
+        items = values.get(key, [])
+        if not isinstance(items, list) or any(
+            not isinstance(item, str) or not item for item in items
+        ):
+            raise GitvarsError(f"Configuration '{key}' must be a list of nonempty strings")
+        values[key] = tuple(items) + tuple(getattr(args, key, None) or ())
+    if "escape" in values and not isinstance(values["escape"], bool):
+        raise GitvarsError("Configuration 'escape' must be true or false")
+    if args.prefix is not None:
+        values["prefix"] = args.prefix
+    if args.escape is not None:
+        values["escape"] = args.escape
+    config = Config(**values)
+    if not config.prefix or any(char in config.prefix for char in "\r\n\\\x00"):
+        raise GitvarsError("Prefix must be nonempty and contain no newline, NUL, or backslash")
+    if config.provider not in {"auto", "github", "gitlab", "bitbucket_cloud"}:
+        raise GitvarsError("Provider must be auto, github, gitlab, or bitbucket_cloud")
+    for pattern in (*config.include, *config.exclude):
+        if pattern.startswith("/") or ".." in pattern.split("/"):
+            raise GitvarsError(f"Glob must be repository-relative: {pattern!r}")
+    for pattern in config.exclude_regex:
+        try:
+            re.compile(pattern)
+        except re.error as exc:
+            raise GitvarsError(f"Invalid exclusion regex {pattern!r}: {exc}") from exc
+    return config
+
+
+def match_glob(path: str, pattern: str) -> bool:
+    """Match whole POSIX paths; ** matches zero or more complete segments."""
+    parts = tuple(path.split("/"))
+    patterns = tuple(pattern.split("/"))
+
+    @cache
+    def match(index: int, pattern_index: int) -> bool:
+        if pattern_index == len(patterns):
+            return index == len(parts)
+        token = patterns[pattern_index]
+        if token == "**":
+            return match(index, pattern_index + 1) or (
+                index < len(parts) and match(index + 1, pattern_index)
+            )
+        return (
+            index < len(parts)
+            and fnmatchcase(parts[index], token)
+            and match(index + 1, pattern_index + 1)
+        )
+
+    return match(0, 0)
+
+
+class Selector:
+    def __init__(self, config: Config):
+        self.config = config
+        self.regexes = tuple(re.compile(pattern) for pattern in config.exclude_regex)
+
+    def excluded(self, relative: str) -> bool:
+        path = Path(relative)
+        candidates = (relative, *(parent.as_posix() for parent in path.parents if parent != Path(".")))
+        return any(
+            any(match_glob(candidate, pattern) for pattern in self.config.exclude)
+            or any(regex.search(candidate) for regex in self.regexes)
+            for candidate in candidates
+        )
+
+    def included(self, relative: str) -> bool:
+        return any(match_glob(relative, pattern) for pattern in self.config.include)

gitvars/errors.py

@@ -0,0 +1,2 @@
+class GitvarsError(Exception):
+    """An actionable configuration, Git, input, or filesystem error."""

gitvars/files.py

@@ -0,0 +1,137 @@
+"""Traversal, destination validation, and per-file atomic writes."""
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import shutil
+import stat
+import tempfile
+
+from .config import Config, Selector
+from .errors import GitvarsError
+from .git import git, repository_root
+
+
+@dataclass(frozen=True)
+class Entry:
+    source: Path
+    relative: str
+    render: bool
+
+
+@dataclass
+class Stats:
+    scanned: int = 0
+    changed: int = 0
+    copied: int = 0
+    skipped: int = 0
+    errors: int = 0
+
+
+def absolute(path: str | Path) -> Path:
+    return Path(os.path.abspath(path))
+
+
+def has_symlink(path: Path) -> bool:
+    return any(part.is_symlink() for part in (path, *path.parents))
+
+
+def prepare_inputs(paths: list[str], config: Config) -> tuple[Path, list[Path]]:
+    inputs = list(dict.fromkeys(absolute(path) for path in paths))
+    for path in inputs:
+        if not path.exists() and not path.is_symlink():
+            raise GitvarsError(f"Input does not exist: {path}")
+        if path.is_dir() and not has_symlink(path) and not config.include:
+            raise GitvarsError("Directory inputs require include patterns in .gitvars or --include; alternatively supply files explicitly")
+    root = repository_root(inputs[0])
+    for path in inputs:
+        if has_symlink(path):
+            continue
+        if repository_root(path) != root:
+            raise GitvarsError("Each invocation must use one Git repository; inputs span multiple repositories")
+    return root, inputs
+
+
+def discover_entries(root: Path, inputs: list[Path], config: Config, stats: Stats) -> list[Entry]:
+    selector = Selector(config)
+    entries: dict[Path, Entry] = {}
+
+    def visit(path: Path, explicit: bool = False) -> None:
+        if has_symlink(path) or ".git" in path.relative_to(root).parts:
+            stats.skipped += 1
+            return
+        relative = path.relative_to(root).as_posix()
+        if relative != "." and selector.excluded(relative):
+            stats.skipped += 1
+            return
+        if path.is_dir():
+            if path != root and (path / ".git").exists():
+                stats.skipped += 1
+                return
+            for child in sorted(path.iterdir()):
+                visit(child)
+        elif path.is_file():
+            render = explicit or selector.included(relative)
+            previous = entries.get(path)
+            entries[path] = Entry(path, relative, render or bool(previous and previous.render))
+        else:
+            stats.skipped += 1
+
+    for path in inputs:
+        # Explicit symlinks can point outside the root; never traverse them.
+        if has_symlink(path):
+            stats.skipped += 1
+            continue
+        visit(path, explicit=path.is_file())
+    return sorted(entries.values(), key=lambda entry: entry.relative)
+
+
+def validate_output(output: Path, inputs: list[Path], root: Path, force: bool) -> None:
+    if has_symlink(output):
+        raise GitvarsError(f"Output directory and its parents must not be symlinks: {output}")
+    for path in inputs:
+        source = path.resolve()
+        if output == source or output in source.parents or (path.is_dir() and source in output.parents):
+            raise GitvarsError(f"Output directory overlaps an input: {output}; choose a disjoint destination")
+    if ".git" in output.parts:
+        raise GitvarsError("Output must not be inside Git metadata (.git)")
+    if output.exists():
+        if not output.is_dir():
+            raise GitvarsError(f"Output path is not a directory: {output}")
+        if any(output.iterdir()) and not force:
+            raise GitvarsError(f"Output directory is not empty: {output}; pass -f/--force to clear it")
+    # --separate-git-dir and linked worktrees need not store metadata under .git.
+    for option in ("--absolute-git-dir", "--git-common-dir"):
+        location = Path(os.fsdecode(git(root, "rev-parse", option).rstrip(b"\n")))
+        metadata = (root / location).resolve()
+        if output == metadata or output in metadata.parents or metadata in output.parents:
+            raise GitvarsError("Output directory must not overlap Git metadata")
+
+
+def prepare_output(output: Path) -> None:
+    if output.exists():
+        for child in output.iterdir():
+            if child.is_dir() and not child.is_symlink():
+                shutil.rmtree(child)
+            else:
+                child.unlink()
+    else:
+        output.mkdir(parents=True)
+
+
+def atomic_write(destination: Path, content: bytes, mode: int) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=f".{destination.name}.gitvars-", dir=destination.parent)
+    temporary = Path(name)
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(content)
+        temporary.chmod(stat.S_IMODE(mode))
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def copy_file(source: Path, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(source, destination)

gitvars/git.py

@@ -0,0 +1,98 @@
+"""Read one immutable commit snapshot using the installed Git executable."""
+
+from dataclasses import dataclass
+from pathlib import Path
+import os
+import subprocess
+
+from .config import Config
+from .errors import GitvarsError
+from .providers import RepositoryURL, resolve_repository_url
+
+
+def git(directory: Path, *arguments: str, optional: bool = False) -> bytes:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(directory), *arguments],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+    except FileNotFoundError as exc:
+        raise GitvarsError("Git is not installed or not on PATH; install Git to use gitvars") from exc
+    if result.returncode and not optional:
+        detail = result.stderr.decode("utf-8", errors="replace").strip()
+        raise GitvarsError(f"Git failed in {directory}: {detail}")
+    return result.stdout if result.returncode == 0 else b""
+
+
+def repository_root(path: Path) -> Path:
+    directory = path if path.is_dir() and not path.is_symlink() else path.parent
+    result = git(directory, "rev-parse", "--show-toplevel", optional=True)
+    if not result:
+        raise GitvarsError(f"Input is outside a Git working tree: {path}")
+    return Path(os.fsdecode(result.rstrip(b"\n"))).resolve()
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    root: Path
+    values: dict[str, str]
+    files: frozenset[str]
+    repository_url: RepositoryURL
+
+    def for_file(self, relative: str) -> dict[str, str]:
+        values = dict(self.values)
+        url = self.repository_url
+        values["file_url"] = (
+            url.provider.file_url(url.base, values["commit"], relative)
+            if relative in self.files and url.base and url.provider else ""
+        )
+        return values
+
+
+def collect_snapshot(root: Path, config: Config) -> Snapshot:
+    commit = git(root, "rev-parse", "--verify", "HEAD", optional=True).decode().strip()
+    if not commit:
+        raise GitvarsError(f"Repository has no commit at HEAD: {root}; create a commit before rendering")
+    fields = (
+        "commit", "commit_short", "author_name", "author_email", "committer_name",
+        "committer_email", "commit_subject", "commit_message", "commit_date",
+    )
+    output = git(
+        root, "show", "--no-patch", "--no-show-signature", "--encoding=UTF-8",
+        "--format=%H%x00%h%x00%an%x00%ae%x00%cn%x00%ce%x00%s%x00%B%x00%aI%x00", commit,
+    )
+    values = dict(zip(fields, output.decode("utf-8", errors="replace").split("\x00")[:len(fields)]))
+    values["branch"] = git(root, "symbolic-ref", "--quiet", "--short", "HEAD", optional=True).decode().strip()
+    tags = git(
+        root, "tag", "--points-at", commit, "--sort=-version:refname", "--no-column", "--color=never",
+    ).decode().splitlines()
+    values["tag"] = tags[0] if tags else ""
+    remote = git(root, "remote", "get-url", "--", config.remote, optional=True).decode().strip() or None
+    url = resolve_repository_url(config, remote, root.name)
+    values["repository"] = url.name
+    values["commit_url"] = url.provider.commit_url(url.base, commit) if url.base and url.provider else ""
+    files = set()
+    for record in git(root, "ls-tree", "-rz", "--full-tree", commit).split(b"\0"):
+        if record:
+            info, path = record.split(b"\t", 1)
+            if info.split()[0] in {b"100644", b"100755"}:
+                files.add(os.fsdecode(path))
+    return Snapshot(root, values, frozenset(files), url)
+
+
+def require_clean_inputs(snapshot: Snapshot, relatives: list[str]) -> None:
+    dirty = set()
+    for staged in (False, True):
+        arguments = ["diff", "--no-ext-diff", "--no-renames", "--name-only", "-z"]
+        if staged:
+            arguments.append("--cached")
+        dirty.update(os.fsdecode(path) for path in git(snapshot.root, *arguments).split(b"\0") if path)
+    unsafe = [path for path in relatives if path not in snapshot.files or path in dirty]
+    if unsafe:
+        sample = ", ".join(unsafe[:5])
+        raise GitvarsError(
+            f"In-place rendering requires clean tracked inputs: {sample}. "
+            "Commit or restore those files, or use --output-dir"
+        )

gitvars/providers.py

@@ -0,0 +1,99 @@
+"""Offline URL parsing and small provider-specific route adapters."""
+
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+import re
+from urllib.parse import quote, unquote, urlsplit, urlunsplit
+
+from .config import Config
+from .errors import GitvarsError
+
+
+@dataclass(frozen=True)
+class Provider:
+    commit_route: str
+    file_route: str
+
+    def commit_url(self, base: str, commit: str) -> str:
+        return f"{base}/{self.commit_route}/{commit}"
+
+    def file_url(self, base: str, commit: str, path: str) -> str:
+        return f"{base}/{self.file_route}/{commit}/{quote(path, safe='/')}"
+
+
+PROVIDERS = {
+    "github": Provider("commit", "blob"),
+    "gitlab": Provider("-/commit", "-/blob"),
+    "bitbucket_cloud": Provider("commits", "src"),
+}
+HOSTS = {"github.com": "github", "gitlab.com": "gitlab", "bitbucket.org": "bitbucket_cloud"}
+
+
+@dataclass(frozen=True)
+class RepositoryURL:
+    name: str
+    base: str | None = None
+    provider: Provider | None = None
+
+
+def remote_parts(remote: str) -> tuple[str | None, str | None, str]:
+    """Return browser base, hostname, and repository name for common remotes."""
+    if "://" in remote:
+        parsed = urlsplit(remote)
+        path = parsed.path.rstrip("/")
+        hostname = parsed.hostname
+        if parsed.scheme in {"http", "https", "ssh", "git"} and hostname:
+            scheme = parsed.scheme if parsed.scheme in {"http", "https"} else "https"
+            host = f"[{hostname}]" if ":" in hostname else hostname
+            if scheme == parsed.scheme and parsed.port:
+                host += f":{parsed.port}"
+            base = urlunsplit((scheme, host, path, "", ""))
+        else:
+            base = None
+    else:
+        scp = re.fullmatch(r"(?:[^@/]+@)?([^/:]+):(.+)", remote)
+        if scp:
+            hostname, path = scp.groups()
+            path = "/" + path.strip("/")
+            base = f"https://{hostname}{path}"
+        else:
+            hostname, path, base = None, remote.rstrip("/"), None
+    if path.endswith(".git"):
+        path = path[:-4]
+        if base is not None:
+            base = base[:-4]
+    name = unquote(PurePosixPath(path).name)
+    if base is not None and len([part for part in path.split("/") if part]) < 2:
+        base = None
+    return base, hostname.lower() if hostname else None, name
+
+
+def resolve_repository_url(config: Config, remote: str | None, directory_name: str) -> RepositoryURL:
+    source = config.url_prefix or remote
+    if source is None:
+        return RepositoryURL(directory_name)
+    try:
+        base, host, name = remote_parts(source)
+        if config.url_prefix:
+            parsed = urlsplit(source)
+            if (
+                parsed.scheme not in {"http", "https"}
+                or not parsed.hostname
+                or parsed.username is not None
+                or parsed.password is not None
+                or parsed.query
+                or parsed.fragment
+                or len([part for part in parsed.path.split("/") if part]) < 2
+                or any(char.isspace() for char in source)
+            ):
+                raise GitvarsError("url_prefix must be an HTTP(S) repository web root, including owner and repository")
+    except ValueError as exc:
+        if config.url_prefix:
+            raise GitvarsError(f"Invalid url_prefix: {exc}") from exc
+        return RepositoryURL(directory_name)
+    provider_name = config.provider if config.provider != "auto" else HOSTS.get(host)
+    if config.url_prefix and provider_name is None:
+        raise GitvarsError("Cannot infer provider from url_prefix; set provider explicitly for self-hosted domains")
+    if provider_name == "bitbucket_cloud" and host != "bitbucket.org":
+        raise GitvarsError("bitbucket_cloud supports bitbucket.org only")
+    return RepositoryURL(name or directory_name, base, PROVIDERS.get(provider_name))

gitvars/render.py

@@ -0,0 +1,44 @@
+"""Single-pass substitution of supported tokens, with optional escaping."""
+
+import difflib
+import re
+
+
+NAMES = (
+    "commit", "commit_short", "author_name", "author_email", "committer_name",
+    "committer_email", "commit_subject", "commit_message", "commit_date",
+    "branch", "tag", "repository", "commit_url", "file_url",
+)
+
+
+class Renderer:
+    def __init__(self, prefix: str, escape: bool):
+        escaped = r"(?P<escaped>\\)?" if escape else ""
+        self.pattern = re.compile(escaped + re.escape(prefix) + r"(?P<name>" + "|".join(NAMES) + r")__")
+        self.escape = escape
+
+    def render(self, text: str, values: dict[str, str]) -> tuple[str, set[str]]:
+        unavailable = set()
+
+        def replace(match: re.Match) -> str:
+            if self.escape and match.group("escaped"):
+                return match.group()[1:]
+            name = match.group("name")
+            value = values[name]
+            if not value:
+                unavailable.add(name)
+            return value
+
+        return self.pattern.sub(replace, text), unavailable
+
+
+def unified_diff(before: str, after: str, relative: str, destination: str | None = None) -> str:
+    parts = []
+    for line in difflib.unified_diff(
+        before.splitlines(keepends=True), after.splitlines(keepends=True),
+        fromfile=f"a/{relative}", tofile=destination or f"b/{relative}",
+    ):
+        parts.append(line)
+        if not line.endswith("\n"):
+            parts.append("\n\\n")
+    return "".join(parts)

gitvars_render-0.1.0.dist-info/METADATA

@@ -0,0 +1,426 @@
+Metadata-Version: 2.4
+Name: gitvars-render
+Version: 0.1.0
+Summary: Render Git provenance into text templates without network access.
+Author: Andres Velasco
+License-Expression: MIT
+Project-URL: Repository, https://github.com/AndresVelasco/gitvars-render
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: demo
+Requires-Dist: markdown-it-py<5,>=4; extra == "demo"
+Dynamic: license-file
+
+# gitvars-render
+
+`gitvars` exists so that ***your deployed assets can point back to their source.***
+
+Git knows the commit, its author, and the code behind a change. `gitvars` carries
+that context into the files you deploy. Add placeholders to your configuration,
+code, or documentation, and replace them with Git metadata during your build—
+including links to the exact commit and source file.
+
+## Why gitvars exists
+
+I built it for a recurring need in data engineering: **labeling data assets and
+pipelines with the version of code behind them.** When inspecting a table or an
+Airflow DAG, I wanted a direct route back to the change that produced it.
+Embedding Git metadata in labels, descriptions, and configuration makes that
+connection easier to follow when investigating an issue or understanding a
+deployment.
+
+The same idea works for Terraform resources, application configuration, and
+documentation. The [example page](https://andresvelasco.github.io/gitvars-render/) uses `gitvars` to fill in its
+Git metadata at build time.
+
+## Installation
+
+The Python distribution is named `gitvars-render` and installs the `gitvars` command.
+The Python import remains `gitvars`. It
+requires Python 3.11+ and Git on `PATH`, with no runtime dependencies or network
+calls during rendering.
+
+Install the package from a source checkout into your Python environment,
+replacing `/path/to/gitvars-render` with the directory containing its `pyproject.toml`:
+
+```sh
+python -m pip install /path/to/gitvars-render
+```
+
+Once this project is published to PyPI, install its release by package name:
+
+```sh
+python -m pip install gitvars-render
+```
+
+## Usage
+
+Run `gitvars` in the Git repository containing the files you want to process.
+There are two commands:
+
+| Command | Behavior |
+| --- | --- |
+| `gitvars render [PATH ...]` | Replace placeholders in selected files, in place by default, or write copies with `--output-dir`. |
+| `gitvars check [PATH ...]` | Read selected files without writing. Exit `1` if rendering would change any file, or `0` if no changes are needed. |
+
+Add `--dry-run` to `render` to preview a unified diff without writing anything.
+Both commands read configuration from the nearest `.gitvars` found by searching
+upward from the **working directory**, not from each input path. Use
+`--config FILE` to select a specific configuration file. A configuration file is optional:
+you can supply file selection and other options on the command line instead.
+
+### Select files and directories
+
+Both commands accept **zero, one, or several positional paths**. Paths are files
+or directories relative to your working directory; absolute paths also work.
+You may mix files and directories, but every input must belong to the same Git
+repository. Overlapping inputs are deduplicated.
+
+| Inputs | Selection |
+| --- | --- |
+| No paths | Scan the current directory recursively. |
+| One or more directories | Scan those directories recursively. |
+| One or more files | Select those files directly; no include patterns are required. |
+
+**Paths choose where to scan; include patterns choose which files to render.**
+Directory scans require `include` patterns in `.gitvars` or repeatable
+`--include` options. Globs are relative to the repository root. Exclusions still
+apply to explicitly supplied files, even though include patterns are unnecessary
+for them.
+
+For example, preview SQL files under `models/` and Markdown files under `docs/`,
+without requiring a configuration file:
+
+```sh
+gitvars render models docs --include '**/*.sql' --include '**/*.md' --dry-run
+```
+
+Or preview two specific files without `--include`:
+
+```sh
+gitvars render models/model.sql docs/pipeline.md --dry-run
+```
+
+To keep selection in configuration, create `.gitvars` at the repository root:
+
+```toml
+include = ["**/*.sql", "**/*.md"]
+exclude = ["build/**", "dist/**", ".venv/**"]
+```
+
+With that configuration, no CLI `--include` is needed. Narrow the scan to the
+two directories, or omit paths to scan the current directory:
+
+```sh
+gitvars render models docs --dry-run
+gitvars check models docs
+gitvars render --dry-run
+```
+
+For the complete configuration options and matching rules, see
+[Configuration](#configuration).
+
+### Choose where rendering writes
+
+`render` defaults to **in-place replacement**. This is intended for fresh CI
+checkouts: substitution consumes the placeholders. Local use is supported, but
+every selected input must be tracked and have no staged or unstaged changes.
+Unrelated modified files do not block rendering. Restore the templates from Git
+before rendering them again for a different commit.
+
+Using the configuration above, render both directories in place:
+
+```sh
+gitvars render models docs
+```
+
+For generated artifacts, keep templates intact and render copies instead:
+
+```sh
+gitvars render models docs --output-dir build
+```
+
+`models/nested/model.sql` becomes `build/models/nested/model.sql`: paths
+are always relative to the repository root, without flattening. Unselected files
+in input directories are copied unchanged as bytes, including images and other
+assets. Excluded files are omitted.
+
+The output directory must be empty or absent. Use `-f` / `--force` to clear a
+nonempty output directory before generating it again. Its contents are removed,
+including files unrelated to the previous run. The flag never permits overlapping
+inputs and outputs: an output directory cannot be inside an input directory,
+equal an input, or contain an input. Symlink destinations and destinations inside
+`.git` are refused. A common safe layout is sibling `models/`, `docs/`, and
+`build/` directories, with only `models docs` as the inputs. Omitting the paths
+would scan the current directory, so a `build/` destination inside it would be
+rejected even if `build/**` is excluded.
+
+```sh
+gitvars render models docs --output-dir build --force
+gitvars render models docs --output-dir build --force --dry-run
+```
+
+`--dry-run` prints unified diffs without changing any files, creating directories,
+or clearing existing output. `check` reports whether rendering would change
+selected files. Both can inspect dirty or untracked inputs.
+
+## Configuration
+
+Use TOML in `.gitvars`. The nearest file found by searching upward from the
+working directory wins. `--config FILE` overrides discovery. A directory input
+requires include patterns from configuration or `--include`; with no paths,
+the input is the working directory.
+
+```toml
+prefix = "__git_"
+escape = true
+remote = "origin"
+provider = "auto"
+include = ["**/*.sql", "**/*.md", "**/*.yml", "**/*.yaml"]
+exclude = ["build/**", "dist/**", ".venv/**"]
+exclude_regex = ['(^|/)README\.md$']
+# Optional repository web root, including owner/group and repository:
+# url_prefix = "https://git.company.com/team/analytics"
+# provider = "gitlab"  # Required for self-hosted hosts.
+```
+
+All selection patterns are **repository-relative**, regardless of the working
+directory or configuration location. Paths use `/`, and matching is case-sensitive:
+
+| Pattern | Matches |
+| --- | --- |
+| `*.md` | Markdown files at the repository root |
+| `**/*.md` | Markdown files at any depth, including the root |
+| `build/**` | The root build directory and everything beneath it |
+| `templates/?.sql` | One-character SQL filenames directly under `templates/` |
+
+`*`, `?`, and character classes match within a path segment. A standalone `**`
+segment matches zero or more directories. Globs match the whole relative path;
+regex exclusions search it. Matching an excluded directory excludes its subtree.
+There are no negation/reinclude rules. `.gitignore` is not implicitly consulted.
+
+CLI `--include`, `--exclude`, and `--exclude-regex` are repeatable and extend their
+configuration lists. CLI `--prefix` and `--escape` / `--no-escape` override scalar
+configuration. Matching any exclusion wins over inclusion or an explicit file.
+
+Symlinks, `.git`, and nested repositories are skipped during traversal. Explicit
+inputs from different repositories are rejected. All files in an invocation use
+one commit snapshot. A repository without a commit at `HEAD` is an error.
+
+## Placeholders
+
+| Placeholder | Value |
+| --- | --- |
+| `__git_commit__` | Full `HEAD` commit SHA |
+| `__git_commit_short__` | Git's abbreviated SHA |
+| `__git_author_name__` | Commit author name |
+| `__git_author_email__` | Commit author email |
+| `__git_committer_name__` | Committer name |
+| `__git_committer_email__` | Committer email |
+| `__git_commit_subject__` | Commit subject |
+| `__git_commit_message__` | Full commit message, including newlines |
+| `__git_commit_date__` | Author date in ISO 8601 with timezone |
+| `__git_branch__` | Current branch; empty in detached HEAD |
+| `__git_tag__` | Highest version-ordered tag pointing at `HEAD`; empty if none |
+| `__git_repository__` | Repository name |
+| `__git_commit_url__` | Commit browser URL, if available |
+| `__git_file_url__` | Input-file permalink at `HEAD`, if the file exists there |
+
+Commit metadata describes checked-out `HEAD`, including when output-directory
+inputs have local edits. It does not identify the deployer or the last author of
+each file. File links refer to the version committed at `HEAD`, which can differ
+from a dirty local input. Tags are ordered using Git's version sort, not creation
+date; only tags available in the local checkout participate.
+
+Supported placeholders are replaced everywhere, including Markdown inline code
+and fenced code blocks. Unknown or incomplete placeholders are left untouched.
+Prefix strings are literal, not regexes. Unavailable known values become empty
+strings, with warnings under `--verbose`.
+
+Escape a supported placeholder with an immediately preceding backslash:
+
+```text
+__git_commit__    -> the actual SHA
+\__git_commit__   -> literal __git_commit__
+```
+
+One escape backslash is consumed; all other backslashes remain unchanged.
+Disable escape handling with `escape = false` or `--no-escape`. Then a backslash
+is ordinary text: `\__git_commit__` becomes a backslash followed by the SHA.
+Replacement is always one-pass; inserted metadata and escaped tokens are never
+processed again during that invocation.
+
+Values are inserted verbatim by default. Use `--html-escape` with `render` or
+`check` to encode inserted values for HTML text and quoted attributes, including
+`&`, `<`, `>`, and quotes. Template text and literal placeholders stay unchanged.
+This is separate from backslash placeholder escaping. Template authors remain
+responsible for quoting and escaping values for other output formats.
+
+## Repository URLs
+
+GitHub, GitLab, and Bitbucket Cloud are supported, including common HTTPS,
+SCP-style SSH, and `ssh://` remotes. `provider = "auto"` recognizes `github.com`,
+`gitlab.com`, and `bitbucket.org`. Self-hosted GitHub/GitLab installations require
+an explicit `provider`. A self-hosted `url_prefix` with `auto` is a configuration
+error; an unrecognized remote without an override simply produces empty links.
+
+`url_prefix` takes precedence over the selected remote for links and repository
+names. Name discovery uses its final path component, then the selected remote's,
+then the local repository-root directory name. A trailing `.git` is removed from
+URL-derived names. The default remote is `origin`. No hosting APIs are used.
+File URLs use the original input's repository-relative path, with components
+URL-encoded, and the full commit SHA. A file absent from `HEAD` has no permalink.
+
+## Files, failures, and exit codes
+
+Only selected files are decoded as UTF-8; there is no binary detection. A selected
+file that cannot be decoded produces an error. Original newline characters,
+including mixed line endings and the UTF-8 BOM, are preserved outside substituted
+values. Multiline metadata is inserted verbatim. File permissions are preserved;
+unchanged in-place files are not rewritten. Each changed file is replaced atomically.
+
+Inputs, repository membership, selections, and destination safety are checked
+before writing or clearing output. In-place clean-input checks also happen before
+writing. Files are then processed sequentially: there is no bulk token validation
+or automatic rollback. A later decoding, reading, or writing failure can leave
+earlier files rendered. Restore affected in-place files from Git, or delete and
+regenerate output-directory contents.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | Successful render/dry-run, even with changes; or check needs no changes |
+| `1` | Check found files rendering would change |
+| `2` | Invalid arguments/configuration, missing Git/commit/repository, dirty in-place inputs, or an I/O/encoding error |
+
+All logging and diagnostics go to stdout. Default output is a concise summary;
+`--verbose` adds paths and unavailable-value warnings, and `--quiet` suppresses
+routine logging. Dry-run diffs and errors remain visible with `--quiet`.
+
+## Development and demo
+
+```sh
+uv sync --locked --extra demo
+uv run --locked --extra demo python -m unittest discover -s tests -v
+```
+
+`uv.lock` is versioned so local development, CI, and demo builds use the same
+resolved dependencies. `--locked` fails if it needs updating. After changing
+dependencies, run `uv lock` and commit both `pyproject.toml` and `uv.lock`.
+The runtime package still has no dependencies; the default development group
+adds the version-comparison helper used by release automation.
+
+To build and preview the page locally:
+
+```sh
+uv run --locked --extra demo python demo/build.py
+uv run --locked --extra demo gitvars render demo/index.html --html-escape --output-dir build --force
+```
+
+| Path | Purpose |
+| --- | --- |
+| `README.md` | Page content, maintained in Markdown. |
+| `demo/layout.html` | Tracked HTML layout and styles. |
+| `demo/index.html` | Generated HTML with Git placeholders intact; ignored by Git. |
+| `build/demo/index.html` | Final rendered page with actual Git values; ignored by Git. Open this file in your browser. |
+
+`demo/build.py` only combines the README and layout into `demo/index.html`,
+leaving the Git placeholders intact. The separate `gitvars render` command
+replaces them in a copy at `build/demo/index.html`, preserving the input path
+under `build/`. `--force` clears an existing `build/` directory before rendering.
+Neither generated HTML file is committed. Run both commands again after editing
+the README or layout. CI uses the same two steps on pushes and pull requests.
+
+The table is inserted immediately after the introduction. Its three columns show
+the literal variable, its replaced value, and its explanation. README examples
+stay literal; only the table's value cells are substituted. Values are escaped
+for HTML, including multiline commit messages. The file URL cell is empty
+because the generated input is absent from `HEAD`; the commit URL still links
+to the source revision. Both commands run once and exit. The optional `demo`
+dependencies are needed only to convert the README to HTML; the gitvars CLI
+itself still has no runtime dependencies.
+
+### GitHub Pages output
+
+On a push to `main`, the Pages workflow first runs `demo/build.py`, then invokes
+`gitvars render` to produce `build/demo/index.html`. It uploads **`build/demo/` as the
+Pages artifact**. That directory becomes the website root, so its `index.html`
+is the homepage. With the default project-site URL, it appears at
+[https://andresvelasco.github.io/gitvars-render/](https://andresvelasco.github.io/gitvars-render/),
+without `build/demo/` in the URL. The workflow can also be run manually.
+
+Select **GitHub Actions** as the repository's Pages publishing source to enable
+deployment, following the [GitHub Pages workflow documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/using-custom-workflows-with-github-pages).
+Generated output is not committed, so the page can link to the exact source
+commit without a self-referential SHA update.
+
+## Publishing releases
+
+The distribution on PyPI and TestPyPI is **`gitvars-render`**. The GitHub
+repository is `AndresVelasco/gitvars-render`; the executable and Python import
+remain `gitvars`. `pyproject.toml` is the single version source, and
+`gitvars --version` reads the installed distribution's metadata.
+
+The publishing workflow is `.github/workflows/publish.yml`:
+
+| Event | Result after successful checks |
+| --- | --- |
+| Pull request | Tests and distribution builds; no publishing. |
+| Push to `main` with no release tags yet | Publish a development build to TestPyPI. |
+| Push to `main` with an unchanged released version | Publish a development build to TestPyPI. |
+| Push to `main` with a version above the latest release tag | Create the matching `vMAJOR.MINOR.PATCH` tag and publish to PyPI. |
+| Push of a matching version tag | Verify the tag, version, and tests, then publish to PyPI. |
+
+With no existing release tags, the first successful `main` build publishes
+`0.1.0.dev...` to TestPyPI. After verifying that build, request the initial
+production release explicitly:
+
+```sh
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+This starts the production publishing workflow, including tests and a check that
+the tag matches the version in `pyproject.toml`. For subsequent releases, update
+the version instead:
+
+```sh
+uv version 0.1.1
+```
+
+Commit the updated `pyproject.toml` and `uv.lock`, preferably in a release PR,
+and merge into `main`. Release versions use stable `MAJOR.MINOR.PATCH` numbers.
+The workflow compares versions numerically, rejects version regressions and
+tag/version mismatches, and never moves an existing tag. It tags the commit CI
+actually tested, even if `main` has advanced. Tag creation and publishing are
+jobs in the same workflow, so no additional token is needed to trigger another
+workflow from an automated tag.
+
+After `v0.1.0`, ordinary pushes publish versions such as
+`0.1.1.dev1230001`: the next patch version plus a serial derived from the
+workflow run ID and attempt. Only the temporary build checkout gets this
+development version; it is not committed. Re-running a failed release on its
+tagged commit retries publishing and skips distributions already uploaded.
+Wheel and source distributions are installed and checked before publishing.
+
+Configure pending or existing trusted publishers separately on PyPI and
+TestPyPI, and create the corresponding GitHub environments:
+
+| Setting | PyPI | TestPyPI |
+| --- | --- | --- |
+| Project name | `gitvars-render` | `gitvars-render` |
+| Repository owner | `AndresVelasco` | `AndresVelasco` |
+| Repository name | `gitvars-render` | `gitvars-render` |
+| Workflow filename | `publish.yml` | `publish.yml` |
+| Environment | `pypi` | `testpypi` |
+
+Publishing uses OIDC trusted publishing; no PyPI API token is stored in GitHub.
+The first upload creates a project configured with a pending publisher. See
+the [PyPI trusted-publishing documentation](https://docs.pypi.org/trusted-publishers/).
+
+CI is configured to run the standard-library test suite on Python 3.11–3.14 on Linux, plus Python
+3.12 on Windows and macOS. The local implementation has been validated on Python
+3.12 and Git 2.43; hosted CI results determine broader compatibility.

gitvars_render-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+gitvars/__init__.py,sha256=dOrcGUCGwsI7eY5okoMN5tfGZTiIwFLGbA0emrCr_0w,311
+gitvars/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+gitvars/cli.py,sha256=3_foDtQKQE_JQap5ywVX9P_5bXuqhd2Ahb_BYKp6WwY,6268
+gitvars/config.py,sha256=ENaJnO8sQUzLzt6jIQS6zV66qSjjpF0n3oOmsL1VMBY,4473
+gitvars/errors.py,sha256=o5eyqRt54gjpQO4q3licTIX4Im0ym6UQXea_uhGY2Ck,103
+gitvars/files.py,sha256=FOx-oPusce5AbP35Cza0f6ePpc5oxfw8HqKSAcjeIH4,5076
+gitvars/git.py,sha256=O7va92e3z53YrB6V0BfZ0C71hqA_85DEJITeQWEVpEs,4174
+gitvars/providers.py,sha256=BjMvEn5hLshJluJuUq4ldnHcryk4mEVKVplqI5AMztc,3858
+gitvars/render.py,sha256=P4rc5gZ2UpEGECjWI3C8rEkN7uvqg2-2L_3V6Wb0sDQ,1520
+gitvars_render-0.1.0.dist-info/licenses/LICENSE,sha256=rz0gH8KmOlLUJMlhOe6Wl5WBf2t8C9JYdzNIP8P17Vc,1078
+gitvars_render-0.1.0.dist-info/METADATA,sha256=wpeYFHdRwZl9tMPzOxb-M4FtgFEhQXoOsbmRF3PlJCU,19645
+gitvars_render-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+gitvars_render-0.1.0.dist-info/entry_points.txt,sha256=UiBID9z_jDVs7eQL1-sn-nnbYBNHw8aCMfbHSMGIcMU,45
+gitvars_render-0.1.0.dist-info/top_level.txt,sha256=o73PHSI1P11rB1LXdeotvqhHenjzJPiXWutOGmrCAJw,8
+gitvars_render-0.1.0.dist-info/RECORD,,

gitvars_render-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitvars_render-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitvars = gitvars.cli:main

gitvars_render-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Velasco Garcia
+
+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.

gitvars_render-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gitvars