Documentation
¶
Overview ¶
Package gitdir owns access to the git common directory — .git in an ordinary checkout, and the main repository's .git when running from a linked worktree.
Entire keeps a lot of state there, deliberately: session state, advisory locks, the checkpoint push queue, the redaction prefix cache, investigation runs, review manifests, and the captured checkpoint-sync election all live in the common dir rather than under .entire, because they are per-clone and must not be committed or walked into a checkpoint tree. That makes this directory the same kind of trust surface .entire is, and it gets the same treatment: one *os.Root per common dir, opened once and shared, with every read and write resolved as a name inside it.
Two properties come from that, and neither survives a call site reverting to os.ReadFile on a joined path:
- Containment. Names here are built from agent-supplied session IDs and investigation run IDs. Several call sites carry hand-written comments explaining that an unvalidated ID would be a path-traversal sink feeding os.RemoveAll. A root makes that structural instead of a precondition each caller has to keep honouring.
- One directory handle per clone. The resolver shells out to git; before this package, strategy.GetGitCommonDir did so on *every* call with no cache at all, on hook paths.
Unlike .entire there is no create/no-create split: the common dir is the repository, so it always exists by the time anything here is called. What needs creating are Entire's own subdirectories inside it, via osroot.MkdirAllNoSymlink.
Index ¶
- func ClearCache()
- func CommonDir(ctx context.Context) (string, error)
- func CommonDirForWorktree(ctx context.Context, worktreeRoot string) (string, error)
- func Open(ctx context.Context) (*os.Root, error)
- func OpenAt(commonDir string) (*os.Root, error)
- func OpenPathIn(commonDir, absPath string) (root *os.Root, name string, err error)
- func Reset()
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClearCache ¶
func ClearCache()
ClearCache forgets the resolved path. Tests that change directory call it; production does not need to, because the cache is keyed by cwd.
func CommonDir ¶
CommonDir returns the absolute path of the git common directory, caching the result per working directory.
Absolute is the load-bearing word. `git rev-parse --git-common-dir` answers relative to the process's directory — from a subdirectory it returns "../../../.git" — and the two implementations this replaced passed that straight through, so every path built on it was only valid while the process stayed put. Resolving it once here means a stored lock path or queue path still names the same file later, and it is what lets Open hold a handle rather than re-resolving a string.
func CommonDirForWorktree ¶
CommonDirForWorktree returns the absolute git common directory for the repository at worktreeRoot, independent of the process's working directory.
Callers acting on a repo passed as an argument (agent import, session adopt) must use this rather than CommonDir: the cwd-resolved form answers for whatever repo the process happens to be running in, which is how test fixtures once leaked session state into a developer's real .git/entire-sessions and hijacked commit linking.
Not cached: the per-cwd cache CommonDir keeps would be wrong here, since the answer varies with the argument rather than with the process.
func Open ¶
Open returns the shared *os.Root over the git common directory. The returned root is owned by this package and shared with every other caller; do not close it.
func OpenAt ¶
OpenAt is Open for an explicit git directory — the common dir for callers that already resolved one or that act on another clone, and the per-worktree git dir for the few things that genuinely live there rather than in the common dir (the rebase/cherry-pick sequence markers).
func OpenPathIn ¶
OpenPathIn returns the shared root for commonDir together with absPath's name inside it, so a consumer holding an absolute path it was handed earlier can still read through the one root rather than through the path.
It refuses a path that is not under commonDir instead of silently reading it. That refusal is only worth anything when commonDir is resolved INDEPENDENTLY of absPath: a caller that derives the base by walking up from the target makes the check vacuous, because the relative path is then correct by construction. settings.clonePreferencesRoot is the one caller, and it recovers the common dir by removing a compile-time constant suffix, which fails loudly on a path of the wrong shape rather than anchoring somewhere else.
(The investigation stores used to be described here as callers. They are not: they hold a commonDir of their own and resolve run ids as names inside it, which is the stronger form. They now live in the entire-investigate plugin and still reach this package through OpenAt.)
func Reset ¶
func Reset()
Reset closes and forgets every cached root, and the resolved path with them. Call it after deleting or replacing a common dir: a root that outlives its directory is a handle to an unlinked inode, so writes through it succeed and land nowhere. The root registry is shared with the other anchors, so this clears those too.
Types ¶
This section is empty.
Source Files