gabriel / muse public
shallow.py python
99 lines 3.4 KB
Raw
sha256:b636f72dcba9e190afb980bece906fa5b717fbde014b76ef023df8cb96e01eb9 docs: expand cache plan with all seven testing tiers and do… Sonnet 4.6 131 days ago
1 """Shallow graft management for Muse repositories.
2
3 A *shallow* repository is one whose local history is intentionally incomplete.
4 The ``.muse/shallow`` file lists the boundary commits: commits whose own
5 snapshots and objects are expected to be present locally, but whose parents
6 are not. The BFS walk in ``run_verify`` stops at these grafts — it does not
7 descend into history beyond the recorded boundary.
8
9 File format::
10
11 # one sha256:-prefixed commit ID per line
12 sha256:abc123...
13 sha256:def456...
14
15 Lines starting with ``#`` and blank lines are ignored. IDs are stored
16 sorted to keep diffs deterministic.
17
18 This mirrors git's ``.git/shallow`` convention and enables the same workflows:
19
20 - **Shallow clones**: pull only the last N commits; mark the boundary.
21 - **Partial pull**: receive new work without fetching full history.
22 - **Unshallow**: ``remove_shallow`` on all grafts to restore full history.
23
24 Integration with ``run_verify``
25 -------------------------------
26 The BFS walk reads the shallow set once at startup. When it would enqueue
27 a parent commit whose ID is in the shallow set, it increments
28 ``shallow_commits`` and does not enqueue that parent's own parents —
29 stopping the walk at the declared boundary.
30
31 Integration with ``muse pull``
32 ------------------------------
33 When a pull advances the local history, the shallow boundary should be
34 updated:
35
36 - Remove the old tip from the shallow set (it is now interior history).
37 - Add the new graft point if the pull was depth-limited.
38 - If the pull was unbounded (``--unshallow``), remove all grafts.
39 """
40
41 from __future__ import annotations
42
43 import pathlib
44
45 from muse.core.paths import shallow_path as _shallow_path
46
47 shallow_path = _shallow_path
48
49
50 def read_shallow(root: pathlib.Path) -> frozenset[str]:
51 """Return the set of shallow graft commit IDs.
52
53 Returns an empty frozenset when no ``.muse/shallow`` file exists or when
54 the file is empty. Comment lines (``#``) and blank lines are silently
55 skipped.
56 """
57 p = _shallow_path(root)
58 if not p.exists():
59 return frozenset()
60 ids: set[str] = set()
61 for line in p.read_text(encoding="utf-8").splitlines():
62 stripped = line.strip()
63 if stripped and not stripped.startswith("#"):
64 ids.add(stripped)
65 return frozenset(ids)
66
67
68 def write_shallow(root: pathlib.Path, commit_ids: set[str]) -> None:
69 """Atomically write the shallow graft file.
70
71 Sorts IDs before writing so the file is deterministic and diffs cleanly.
72 Creates ``.muse/`` if it does not exist. Writing an empty set produces
73 an empty file (``is_shallow`` returns ``False`` in that case).
74 """
75 p = _shallow_path(root)
76 p.parent.mkdir(parents=True, exist_ok=True)
77 content = "\n".join(sorted(commit_ids)) + "\n" if commit_ids else ""
78 p.write_text(content, encoding="utf-8")
79
80
81 def add_shallow(root: pathlib.Path, commit_id: str) -> None:
82 """Add *commit_id* to the shallow graft set. Idempotent."""
83 current = set(read_shallow(root))
84 current.add(commit_id)
85 write_shallow(root, current)
86
87
88 def remove_shallow(root: pathlib.Path, commit_id: str) -> None:
89 """Remove *commit_id* from the shallow graft set. No-op if absent."""
90 current = set(read_shallow(root))
91 current.discard(commit_id)
92 write_shallow(root, current)
93
94
95 def is_shallow(root: pathlib.Path) -> bool:
96 """Return ``True`` when ``.muse/shallow`` exists and contains at least
97 one commit ID.
98 """
99 return bool(read_shallow(root))
File History 2 commits
sha256:b636f72dcba9e190afb980bece906fa5b717fbde014b76ef023df8cb96e01eb9 docs: expand cache plan with all seven testing tiers and do… Sonnet 4.6 131 days ago
sha256:7f9e2ef5286aedad9c1e6011b4c46ca27f39dbdad6e3409357e36b26e46b3b7c docs: docstring sprint for-each-ref→hotspots — idiomatic ru… Sonnet 4.6 patch 138 days ago