| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217 |
- """What a worktree holds that neither git nor an archive can bring back.
- Every path that deletes a tree (the sweep, the classic clean-tree pruner, exit-time Archive,
- subagent finalization, the attended ``hermes worktree prune``) asks :func:`removal_blocker`
- first; anything it names keeps the tree. The rule: a tree may only be removed when everything
- that is not reproducible is in git or in the archive. Not reproducible:
- * an embedded repository anywhere below the tree, ignored or not (``build/tool/.git``, a nested
- worktree): its private commits live only on disk (``keep-unarchivable``);
- * a commit held only by a per-worktree ref (``refs/worktree/*``, ``refs/bisect/*``,
- ``refs/rewritten/*``), which dies with the tree's admin dir (``keep-worktree-refs``);
- * an untracked file the snapshot skipped for size (``keep-large-untracked``).
- Ignored files (``.env`` copies, caches, build and test output) are disposable: they are not
- archived and are deleted with the tree. Only an embedded repository inside an ignored directory
- keeps it, because its commits may exist nowhere else.
- :func:`hidden_index_edits` finds skip-worktree / assume-unchanged files whose bytes differ from
- the index: ``git status`` never reports them, so dirty checks must add them.
- """
- from __future__ import annotations
- import os
- import subprocess
- from dataclasses import dataclass, field
- from pathlib import Path
- from typing import Optional
- # Dependency stores and caches: never descended, not even to look for an embedded repository.
- _OPAQUE_DIRS = frozenset({
- "node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache", ".ruff_cache",
- ".tox", ".next", ".turbo", ".cache", ".gradle",
- })
- _PER_WORKTREE_REFS = ("refs/worktree/", "refs/bisect/", "refs/rewritten/")
- _MAX_ENTRIES = 200_000 # per tree; past this an embedded repository cannot be ruled out -> keep
- _NAMED = 5 # offenders named in a reason
- KEEP_UNARCHIVABLE = "keep-unarchivable"
- KEEP_WORKTREE_REFS = "keep-worktree-refs"
- KEEP_LARGE_UNTRACKED = "keep-large-untracked"
- KEEP_SUBMODULE_WORK = "keep-submodule-work"
- def _env(wt: Path) -> dict:
- from hermes_cli.worktree_archive import _env as archive_env
- return {**archive_env(wt), "GIT_OPTIONAL_LOCKS": "0"}
- def _git(args, wt: Path, env, timeout: float = 120) -> str:
- from hermes_cli.worktree_archive import _ok
- return _ok(args, wt, env, timeout=timeout)
- @dataclass
- class _Scan:
- embedded: list = field(default_factory=list)
- entries: int = 0
- truncated: bool = False
- def _walk(scan: _Scan, wt: Path, rel_dir: str) -> None:
- """Below ignored *rel_dir*: record nested ``.git`` entries. Symlinks are not followed."""
- stack = [rel_dir]
- while stack and not scan.truncated:
- rel = stack.pop()
- try:
- entries = list(os.scandir(wt / rel))
- except OSError:
- continue
- for entry in entries:
- scan.entries += 1
- if scan.entries > _MAX_ENTRIES:
- scan.truncated = True
- return
- child = f"{rel}/{entry.name}"
- if entry.name == ".git":
- scan.embedded.append(rel)
- continue
- if entry.is_dir(follow_symlinks=False) and entry.name not in _OPAQUE_DIRS:
- stack.append(child)
- def _ignored_entries(wt: Path, env) -> list[str]:
- """Ignored paths, whole ignored directories collapsed to ``dir/``. ``ls-files --directory``
- hits an internal error on some trees (git 2.53: "directory entry not superset of prefix");
- ``status --ignored`` reports the same set."""
- from hermes_cli.worktree_archive import ArchiveError
- try:
- out = _git(["ls-files", "--others", "--ignored", "--exclude-standard", "--directory",
- "--no-empty-directory", "-z"], wt, env)
- return [p for p in out.split("\0") if p]
- except ArchiveError:
- out = _git(["status", "--porcelain", "-z", "--ignored=traditional", "--untracked-files=normal",
- "--no-renames"], wt, env)
- return [e[3:] for e in out.split("\0") if e.startswith("!! ")]
- def scan_tree(wt_path) -> _Scan:
- """Embedded repositories of *wt_path*, ignored or not. Read-only.
- Untracked non-ignored repositories are reported by ``ls-files`` itself (``dir/``); ignored
- ones hide inside collapsed ignored directories, so those are walked (bounded; dependency
- stores are never descended). Raises ``ArchiveError`` when git fails.
- """
- wt = Path(wt_path)
- env = _env(wt)
- scan = _Scan()
- # Without --directory git descends untracked dirs and lists each embedded repository as "dir/".
- untracked = _git(["ls-files", "--others", "--exclude-standard", "-z"], wt, env)
- scan.embedded += [p.rstrip("/") for p in untracked.split("\0") if p.endswith("/")]
- for rel in _ignored_entries(wt, env):
- rel_clean = rel.rstrip("/")
- path = wt / rel_clean
- if not rel.endswith("/") or path.is_symlink() or rel_clean.rsplit("/", 1)[-1] in _OPAQUE_DIRS:
- continue
- if (path / ".git").exists():
- scan.embedded.append(rel_clean)
- continue
- _walk(scan, wt, rel_clean)
- if scan.truncated:
- break
- return scan
- def hidden_index_edits(wt_path, env=None) -> list[str]:
- """Skip-worktree / assume-unchanged paths whose disk state differs from the index.
- ``git status`` trusts both flags and reports nothing. A skip-worktree file missing from disk
- is a sparse checkout, not an edit; a missing assume-unchanged file is a deletion. Raises
- ``ArchiveError`` when git fails.
- """
- wt = Path(wt_path)
- env = env or _env(wt)
- flagged = []
- for record in _git(["ls-files", "-v", "-s", "-z"], wt, env).split("\0"):
- meta, _, rel = record.partition("\t")
- parts = meta.split()
- if not rel or len(parts) != 4 or not (parts[0] == "S" or parts[0].islower()):
- continue
- path = wt / rel
- if not os.path.lexists(path):
- if parts[0] != "S":
- flagged.append(rel) # assume-unchanged file deleted
- continue
- flagged.append((rel, parts[1], parts[2]))
- edits = [f for f in flagged if isinstance(f, str)]
- for rel, mode, sha in (f for f in flagged if not isinstance(f, str)):
- path = wt / rel
- if mode == "120000":
- data = os.readlink(path).encode("utf-8", "surrogateescape") if path.is_symlink() else None
- else:
- data = None if path.is_symlink() or not path.is_file() else path.read_bytes()
- if data is None:
- edits.append(rel) # type changed
- continue
- if _hash(wt, env, data, rel, raw=True) != sha and _hash(wt, env, data, rel, raw=False) != sha:
- edits.append(rel)
- return edits
- def _hash(wt: Path, env, data: bytes, rel: str, *, raw: bool) -> str:
- args = ["hash-object", "--stdin"] + (["--no-filters"] if raw else [f"--path={rel}"])
- result = subprocess.run(["git", *args], cwd=str(wt), env=env, input=data, capture_output=True,
- timeout=60, check=False)
- return result.stdout.decode("ascii", "replace").strip() if result.returncode == 0 else ""
- def private_worktree_refs(wt_path, env=None) -> list[str]:
- """Per-worktree refs of *wt_path* holding commits no branch, tag, remote or archive reaches.
- They live in the tree's admin dir and vanish with it. Raises ``ArchiveError`` when git fails.
- """
- wt = Path(wt_path)
- env = env or _env(wt)
- out = _git(["for-each-ref", "--format=%(refname)%00%(objectname)", *_PER_WORKTREE_REFS], wt, env)
- private = []
- for line in out.splitlines():
- name, _, sha = line.partition("\0")
- if sha and _git(["rev-list", "--max-count=1", sha, "--not", "--branches", "--tags", "--remotes",
- "--glob=refs/hermes/archive/*"], wt, env).strip():
- private.append(name)
- return private
- def _named(paths: list, more: bool = False) -> str:
- extra = len(paths) - _NAMED
- tail = f" (+{extra} more)" if extra > 0 else (" (+more)" if more else "")
- return ", ".join(paths[:_NAMED]) + tail
- def removal_blocker(wt_path, *, skipped: Optional[list] = None, gitlinks: bool = False
- ) -> Optional[tuple[str, str]]:
- """``(keep-action, reason)`` when removing *wt_path* would lose something, else None.
- *skipped* is the snapshot's ``skipped_untracked`` list (or the oversize files a preflight
- would skip). *gitlinks* refuses any submodule (archive paths); without it only a checked-out
- or retained module repository blocks. Any failure to verify blocks. Read-only.
- """
- from hermes_cli.worktree_archive import ArchiveError, submodule_work
- try:
- why = submodule_work(wt_path, gitlinks=gitlinks)
- if why:
- return KEEP_SUBMODULE_WORK, why
- scan = scan_tree(wt_path)
- if scan.embedded:
- return KEEP_UNARCHIVABLE, f"embedded repository {scan.embedded[0]} cannot be archived"
- if scan.truncated:
- return KEEP_UNARCHIVABLE, f"over {_MAX_ENTRIES} ignored entries; cannot rule out an embedded repository"
- refs = private_worktree_refs(wt_path)
- if refs:
- return KEEP_WORKTREE_REFS, f"per-worktree ref {_named(refs)} holds commits no branch has"
- if skipped:
- return KEEP_LARGE_UNTRACKED, f"untracked file(s) over the archive size cap: {_named([s['path'] for s in skipped])}"
- except (ArchiveError, OSError, subprocess.SubprocessError) as exc:
- return KEEP_UNARCHIVABLE, f"could not verify the tree is safe to remove: {exc}"
- return None
|