git-history-sanitize 0.1.0__tar.gz

git_history_sanitize-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Git History Sanitize contributors
+
+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.

git_history_sanitize-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: git-history-sanitize
+Version: 0.1.0
+Summary: Create independently verifiable sanitized Git histories
+Author: f4irline
+Maintainer: f4irline
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/f4irline/git-history-sanitize
+Project-URL: Repository, https://github.com/f4irline/git-history-sanitize
+Project-URL: Issues, https://github.com/f4irline/git-history-sanitize/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Git History Sanitize
+
+Git History Sanitize creates a new, standalone Git database from an existing
+repository according to a declarative policy. It is a history-rewriting and
+verification tool, not a container or runtime sandbox.
+
+It never mutates the source repository. Rewrites happen in a disposable clone,
+the completed bare repository is independently verified, and it is atomically
+moved to the requested output path only after verification succeeds.
+
+The original sandbox-specific prototype is preserved in
+[`proto/`](proto/). It demonstrates one possible consumer of a sanitized Git
+database, but is not part of this tool. The separate `examples/` namespace is
+reserved for samples that use this tool.
+
+## Choose an installation
+
+| Situation | Recommended route |
+| --- | --- |
+| CI, Docker, devcontainer, or sandbox integration | Digest-pinned GHCR image |
+| Developer workstation with supported prerequisites | Pinned PyPI package |
+| Air-gapped or internally mirrored environment | Source distribution or mirrored OCI image |
+
+### Production OCI image
+
+The public image is the recommended production installation because it bundles
+the supported Git, Python, and `git-filter-repo` runtime. Pin the published
+digest rather than a mutable tag:
+
+```bash
+docker run --rm \
+  -v "$PWD/.git:/input.git:ro" \
+  -v "$PWD/policy.yml:/policy.yml:ro" \
+  -v "$PWD/build:/output" \
+  ghcr.io/f4irline/git-history-sanitize@sha256:<published-digest> \
+  rewrite --source /input.git --output /output/sanitized.git --policy /policy.yml
+```
+
+### PyPI command-line package
+
+Install a pinned release with `pipx`:
+
+```bash
+pipx install git-history-sanitize==<version>
+git-history-sanitize doctor
+```
+
+The PyPI package requires Git 2.36 or later and `git-filter-repo` on `PATH`.
+Use `doctor` to confirm the installed tools before processing a repository. The
+OCI image is the supported alternative when supplying those prerequisites on a
+workstation or runner is inconvenient.
+
+## Requirements
+
+- Python 3.11 or later
+- Git 2.36 or later
+- `git-filter-repo` on `PATH`
+
+For development from a checkout:
+
+```bash
+pipx install .
+```
+
+## Policy
+
+```yaml
+version: 1
+
+history:
+  cutoff: "2026-09-03T00:00:00+03:00"
+  prefixMessage: "[sanitized]"
+
+paths:
+  exclude:
+    - secret.json
+    - infra/
+
+commits:
+  mixedMessage: "[sanitized]"
+
+refs:
+  keep:
+    - HEAD
+```
+
+The policy parser intentionally accepts a restricted, security-auditable YAML
+subset: mappings, indented mappings, scalar values, and `-` lists. Strings may
+be quoted. Timestamps must be RFC 3339 values with explicit timezones.
+
+Use either `history.cutoff` or `history.cutoffCommit`. A cutoff timestamp is
+compared with committer timestamps; the cutoff commit itself is retained.
+
+## Usage
+
+```bash
+git-history-sanitize doctor
+
+git-history-sanitize plan \
+  --source .git \
+  --policy .git-history-sanitize.yml
+
+git-history-sanitize rewrite \
+  --source .git \
+  --output build/sanitized.git \
+  --policy .git-history-sanitize.yml
+
+git-history-sanitize verify \
+  --repository build/sanitized.git \
+  --policy .git-history-sanitize.yml
+```
+
+`rewrite` always creates a parentless synthetic root with the configured
+prefix message. It retains the tree at the first allowed commit, removes
+pre-cutoff commits, then filters sensitive paths from the shortened history.
+Mixed commits retain allowed file changes but have their messages replaced.
+Sensitive-only commits are pruned when they become empty.
+
+The first release supports a single linear retained branch. Merge histories,
+non-monotonic cutoff timestamps, and unsupported refs fail closed instead of
+producing an ambiguous rewrite.
+
+## Container image
+
+Build the OCI image:
+
+```bash
+docker buildx build --load -t git-history-sanitize:local -f Containerfile .
+```
+
+Use it with a read-only Git input and writable output directory:
+
+```bash
+docker run --rm \
+  -v "$PWD/.git:/input.git:ro" \
+  -v "$PWD/.git-history-sanitize.yml:/policy.yml:ro" \
+  -v "$PWD/build:/output" \
+  git-history-sanitize:local rewrite \
+    --source /input.git \
+    --output /output/sanitized.git \
+    --policy /policy.yml
+```
+
+Run the isolated package tests with:
+
+```bash
+docker buildx build --target test -f Containerfile .
+```
+
+## Verification
+
+Verification checks the cutoff, synthetic root, configured paths, retained
+refs, remotes, reflogs, backup metadata, and unreachable objects. It can print
+a JSON report:
+
+```bash
+git-history-sanitize verify \
+  --repository build/sanitized.git \
+  --policy .git-history-sanitize.yml \
+  --json
+```
+
+The report intentionally contains no source-to-output mappings or removed
+commit messages.

git_history_sanitize-0.1.0/README.md

@@ -0,0 +1,164 @@
+# Git History Sanitize
+
+Git History Sanitize creates a new, standalone Git database from an existing
+repository according to a declarative policy. It is a history-rewriting and
+verification tool, not a container or runtime sandbox.
+
+It never mutates the source repository. Rewrites happen in a disposable clone,
+the completed bare repository is independently verified, and it is atomically
+moved to the requested output path only after verification succeeds.
+
+The original sandbox-specific prototype is preserved in
+[`proto/`](proto/). It demonstrates one possible consumer of a sanitized Git
+database, but is not part of this tool. The separate `examples/` namespace is
+reserved for samples that use this tool.
+
+## Choose an installation
+
+| Situation | Recommended route |
+| --- | --- |
+| CI, Docker, devcontainer, or sandbox integration | Digest-pinned GHCR image |
+| Developer workstation with supported prerequisites | Pinned PyPI package |
+| Air-gapped or internally mirrored environment | Source distribution or mirrored OCI image |
+
+### Production OCI image
+
+The public image is the recommended production installation because it bundles
+the supported Git, Python, and `git-filter-repo` runtime. Pin the published
+digest rather than a mutable tag:
+
+```bash
+docker run --rm \
+  -v "$PWD/.git:/input.git:ro" \
+  -v "$PWD/policy.yml:/policy.yml:ro" \
+  -v "$PWD/build:/output" \
+  ghcr.io/f4irline/git-history-sanitize@sha256:<published-digest> \
+  rewrite --source /input.git --output /output/sanitized.git --policy /policy.yml
+```
+
+### PyPI command-line package
+
+Install a pinned release with `pipx`:
+
+```bash
+pipx install git-history-sanitize==<version>
+git-history-sanitize doctor
+```
+
+The PyPI package requires Git 2.36 or later and `git-filter-repo` on `PATH`.
+Use `doctor` to confirm the installed tools before processing a repository. The
+OCI image is the supported alternative when supplying those prerequisites on a
+workstation or runner is inconvenient.
+
+## Requirements
+
+- Python 3.11 or later
+- Git 2.36 or later
+- `git-filter-repo` on `PATH`
+
+For development from a checkout:
+
+```bash
+pipx install .
+```
+
+## Policy
+
+```yaml
+version: 1
+
+history:
+  cutoff: "2026-09-03T00:00:00+03:00"
+  prefixMessage: "[sanitized]"
+
+paths:
+  exclude:
+    - secret.json
+    - infra/
+
+commits:
+  mixedMessage: "[sanitized]"
+
+refs:
+  keep:
+    - HEAD
+```
+
+The policy parser intentionally accepts a restricted, security-auditable YAML
+subset: mappings, indented mappings, scalar values, and `-` lists. Strings may
+be quoted. Timestamps must be RFC 3339 values with explicit timezones.
+
+Use either `history.cutoff` or `history.cutoffCommit`. A cutoff timestamp is
+compared with committer timestamps; the cutoff commit itself is retained.
+
+## Usage
+
+```bash
+git-history-sanitize doctor
+
+git-history-sanitize plan \
+  --source .git \
+  --policy .git-history-sanitize.yml
+
+git-history-sanitize rewrite \
+  --source .git \
+  --output build/sanitized.git \
+  --policy .git-history-sanitize.yml
+
+git-history-sanitize verify \
+  --repository build/sanitized.git \
+  --policy .git-history-sanitize.yml
+```
+
+`rewrite` always creates a parentless synthetic root with the configured
+prefix message. It retains the tree at the first allowed commit, removes
+pre-cutoff commits, then filters sensitive paths from the shortened history.
+Mixed commits retain allowed file changes but have their messages replaced.
+Sensitive-only commits are pruned when they become empty.
+
+The first release supports a single linear retained branch. Merge histories,
+non-monotonic cutoff timestamps, and unsupported refs fail closed instead of
+producing an ambiguous rewrite.
+
+## Container image
+
+Build the OCI image:
+
+```bash
+docker buildx build --load -t git-history-sanitize:local -f Containerfile .
+```
+
+Use it with a read-only Git input and writable output directory:
+
+```bash
+docker run --rm \
+  -v "$PWD/.git:/input.git:ro" \
+  -v "$PWD/.git-history-sanitize.yml:/policy.yml:ro" \
+  -v "$PWD/build:/output" \
+  git-history-sanitize:local rewrite \
+    --source /input.git \
+    --output /output/sanitized.git \
+    --policy /policy.yml
+```
+
+Run the isolated package tests with:
+
+```bash
+docker buildx build --target test -f Containerfile .
+```
+
+## Verification
+
+Verification checks the cutoff, synthetic root, configured paths, retained
+refs, remotes, reflogs, backup metadata, and unreachable objects. It can print
+a JSON report:
+
+```bash
+git-history-sanitize verify \
+  --repository build/sanitized.git \
+  --policy .git-history-sanitize.yml \
+  --json
+```
+
+The report intentionally contains no source-to-output mappings or removed
+commit messages.

git_history_sanitize-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "git-history-sanitize"
+version = "0.1.0"
+description = "Create independently verifiable sanitized Git histories"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "f4irline"}]
+maintainers = [{name = "f4irline"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+
+[project.scripts]
+git-history-sanitize = "git_history_sanitize.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/f4irline/git-history-sanitize"
+Repository = "https://github.com/f4irline/git-history-sanitize"
+Issues = "https://github.com/f4irline/git-history-sanitize/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.unittest]
+start-directory = "tests"

git_history_sanitize-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

git_history_sanitize-0.1.0/src/git_history_sanitize/__init__.py

@@ -0,0 +1,3 @@
+"""Git History Sanitize."""
+
+__version__ = "0.1.0"

git_history_sanitize-0.1.0/src/git_history_sanitize/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

git_history_sanitize-0.1.0/src/git_history_sanitize/cleanup.py

@@ -0,0 +1,35 @@
+"""Remove metadata and objects that must not survive sanitization."""
+
+from __future__ import annotations
+
+import shutil
+
+from .git import Repository
+
+
+def retain_head_only(repository: Repository) -> str:
+    head_ref = repository.head_ref()
+    for remote in repository.text("remote").splitlines():
+        if remote:
+            repository.run("remote", "remove", remote)
+    for ref in repository.text("for-each-ref", "--format=%(refname)").splitlines():
+        if ref and ref != head_ref:
+            repository.run("update-ref", "-d", ref)
+    branch = head_ref.removeprefix("refs/heads/")
+    repository.run("config", "--local", "--remove-section", f"branch.{branch}", check=False)
+    return head_ref
+
+
+def cleanup(repository: Repository) -> None:
+    retain_head_only(repository)
+    repository.run(
+        "reflog", "expire", "--expire=now", "--expire-unreachable=now", "--all"
+    )
+    for path in (
+        repository.git_dir / "logs",
+        repository.git_dir / "refs" / "original",
+        repository.git_dir / "filter-repo",
+    ):
+        if path.exists():
+            shutil.rmtree(path)
+    repository.run("gc", "--prune=now", "--aggressive")

git_history_sanitize-0.1.0/src/git_history_sanitize/cli.py

@@ -0,0 +1,88 @@
+"""Command-line interface for Git History Sanitize."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+
+from .engine import plan, rewrite
+from .errors import SanitizeError
+from .git import ensure_dependencies
+from .policy import Policy
+from .verify import verify
+
+
+def _policy(path: str) -> Policy:
+    return Policy.from_file(path)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="git-history-sanitize")
+    subcommands = parser.add_subparsers(dest="command", required=True)
+
+    doctor = subcommands.add_parser("doctor", help="check required Git tooling")
+    doctor.add_argument("--json", action="store_true")
+
+    preview = subcommands.add_parser("plan", help="inspect a proposed rewrite")
+    preview.add_argument("--source", required=True)
+    preview.add_argument("--policy", required=True)
+    preview.add_argument("--json", action="store_true")
+
+    rewrite_command = subcommands.add_parser("rewrite", help="create sanitized output")
+    rewrite_command.add_argument("--source", required=True)
+    rewrite_command.add_argument("--output", required=True)
+    rewrite_command.add_argument("--policy", required=True)
+    rewrite_command.add_argument("--json", action="store_true")
+
+    verification = subcommands.add_parser("verify", help="verify sanitized output")
+    verification.add_argument("--repository", required=True)
+    verification.add_argument("--policy", required=True)
+    verification.add_argument("--forbid", action="append", default=[])
+    verification.add_argument("--json", action="store_true")
+    return parser
+
+
+def _print(value: object, as_json: bool) -> None:
+    if as_json:
+        if hasattr(value, "to_dict"):
+            print(json.dumps(value.to_dict(), sort_keys=True))
+        elif hasattr(value, "to_json"):
+            print(value.to_json())
+        else:
+            print(json.dumps(asdict(value), sort_keys=True))
+        return
+    if hasattr(value, "verification"):
+        print(f"Sanitized HEAD: {value.verification.head}")
+        print(f"Commits in output: {value.verification.commit_count}")
+        return
+    if hasattr(value, "source_commits"):
+        print(f"Source commits: {value.source_commits}")
+        print(f"Pre-cutoff commits: {value.discarded_commits}")
+        print(f"Commits before path filtering: {value.retained_commits_before_path_filter}")
+        return
+    print("Verification passed.")
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = _parser().parse_args(argv)
+    try:
+        if arguments.command == "doctor":
+            result = ensure_dependencies()
+            print(json.dumps(result, sort_keys=True) if arguments.json else "\n".join(result.values()))
+            return 0
+        policy = _policy(arguments.policy)
+        if arguments.command == "plan":
+            _print(plan(arguments.source, policy), arguments.json)
+        elif arguments.command == "rewrite":
+            _print(rewrite(arguments.source, arguments.output, policy), arguments.json)
+        elif arguments.command == "verify":
+            _print(
+                verify(arguments.repository, policy, tuple(arguments.forbid)),
+                arguments.json,
+            )
+        return 0
+    except SanitizeError as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 2

git_history_sanitize-0.1.0/src/git_history_sanitize/compact.py

@@ -0,0 +1,134 @@
+"""Cutoff compaction for a single linear retained Git branch."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+
+from .errors import SanitizeError
+from .git import Repository
+from .policy import Policy
+
+
+@dataclass(frozen=True)
+class CompactResult:
+    original_commits: int
+    discarded_commits: int
+    boundary_commit: str
+    synthetic_root: str
+
+
+def _commits(repository: Repository) -> list[str]:
+    commits = repository.text("rev-list", "--reverse", "--topo-order", "HEAD").splitlines()
+    if not commits:
+        raise SanitizeError("Cannot compact an empty repository")
+    previous: str | None = None
+    for commit in commits:
+        parents = repository.text("show", "-s", "--format=%P", commit).split()
+        if parents != ([] if previous is None else [previous]):
+            raise SanitizeError(
+                "Version 1 cutoff compaction requires a linear retained HEAD history"
+            )
+        previous = commit
+    return commits
+
+
+def _boundary_index(repository: Repository, commits: list[str], policy: Policy) -> int:
+    if policy.history.cutoff_commit:
+        resolved = repository.text(
+            "rev-parse", "--verify", f"{policy.history.cutoff_commit}^{{commit}}"
+        )
+        try:
+            return commits.index(resolved)
+        except ValueError as error:
+            raise SanitizeError("history.cutoffCommit is not reachable from HEAD") from error
+
+    cutoff = policy.history.cutoff_epoch
+    assert cutoff is not None
+    allowed: int | None = None
+    for index, commit in enumerate(commits):
+        if int(repository.text("show", "-s", "--format=%ct", commit)) >= cutoff:
+            allowed = index
+            break
+    if allowed is None:
+        raise SanitizeError("No retained commit exists at or after history.cutoff")
+    for commit in commits[allowed:]:
+        if int(repository.text("show", "-s", "--format=%ct", commit)) < cutoff:
+            raise SanitizeError(
+                "Committer timestamps cross the cutoff more than once; refusing "
+                "an ambiguous history rewrite"
+            )
+    return allowed
+
+
+def _metadata(repository: Repository, commit: str) -> dict[str, str]:
+    fields = repository.run(
+        "show",
+        "-s",
+        "--format=%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%cI",
+        commit,
+    ).rstrip(b"\n").split(b"\x00")
+    if len(fields) != 6:
+        raise SanitizeError(f"Cannot read commit metadata for {commit}")
+    keys = (
+        "GIT_AUTHOR_NAME",
+        "GIT_AUTHOR_EMAIL",
+        "GIT_AUTHOR_DATE",
+        "GIT_COMMITTER_NAME",
+        "GIT_COMMITTER_EMAIL",
+        "GIT_COMMITTER_DATE",
+    )
+    environment = os.environ.copy()
+    environment.update(
+        {key: value.decode("utf-8", "surrogateescape") for key, value in zip(keys, fields)}
+    )
+    return environment
+
+
+def _message(repository: Repository, commit: str) -> bytes:
+    raw = repository.run("cat-file", "commit", commit)
+    try:
+        return raw.split(b"\n\n", 1)[1]
+    except IndexError as error:
+        raise SanitizeError(f"Malformed commit object {commit}") from error
+
+
+def _create_commit(
+    repository: Repository, source: str, parent: str | None, message: bytes
+) -> str:
+    tree = repository.text("rev-parse", f"{source}^{{tree}}")
+    command = ["git", "-C", str(repository.path), "commit-tree", tree]
+    if parent:
+        command.extend(["-p", parent])
+    command.extend(["-F", "-"])
+    result = subprocess.run(
+        command,
+        input=message,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=_metadata(repository, source),
+    )
+    if result.returncode:
+        raise SanitizeError("Could not recreate a sanitized commit")
+    return result.stdout.decode().strip()
+
+
+def compact(repository: Repository, policy: Policy) -> CompactResult:
+    commits = _commits(repository)
+    boundary_index = _boundary_index(repository, commits, policy)
+    boundary = commits[boundary_index]
+    synthetic_root = _create_commit(
+        repository, boundary, None, f"{policy.history.prefix_message}\n".encode()
+    )
+    new_head = synthetic_root
+    for commit in commits[boundary_index + 1 :]:
+        new_head = _create_commit(repository, commit, new_head, _message(repository, commit))
+
+    repository.run("update-ref", repository.head_ref(), new_head, commits[-1])
+    return CompactResult(
+        original_commits=len(commits),
+        discarded_commits=boundary_index,
+        boundary_commit=boundary,
+        synthetic_root=synthetic_root,
+    )