Documentation
¶
Index ¶
- Constants
- Variables
- func EnvWithoutRepoOverrides() []string
- func OpenCurrent(ctx context.Context) (*git.Repository, error)
- func OpenCurrentOrCwd(ctx context.Context) (*git.Repository, error)
- func OpenPath(repoRoot string) (*git.Repository, error)
- func ResolveCommonGitPath(dotGitPath string) (string, error)
- func ResolveDotGitPath(repoRoot string) (string, error)
- func SetStatusBudgetBreachedForTesting(breached bool)
- func Status(_ context.Context, repo *git.Repository) (git.Status, error)
- func StatusWithBudget(ctx context.Context, repo *git.Repository) (git.Status, error)
Constants ¶
const StatusWalkBudget = 20 * time.Second
StatusWalkBudget bounds the wall-clock time of one worktree status read on the agent-hook capture paths — the go-git walk in StatusWithBudget and the first-checkpoint `git status` subprocess in the checkpoint store. Agents time out their hooks at roughly 60s (Claude Code's default), but a timed-out hook PROCESS is not killed — an unbounded walk over a pathological worktree (e.g. a stray `git init` in $HOME with no .gitignore) has been observed grinding for hours at gigabytes of RSS after the agent gave up. 20s is chosen as far beyond any healthy repository (a warm walk over a large working set finishes in seconds) while leaving the remaining ~40s of the agent's timeout for the rest of the capture path — transcript copy, tree building, state writes — so the hook still degrades gracefully and exits instead of being orphaned.
Variables ¶
var ErrStatusBudgetExceeded = errors.New("worktree status walk exceeded time budget")
ErrStatusBudgetExceeded reports that a worktree status walk was abandoned because it exceeded StatusWalkBudget. Capture is fail-open: hook-path callers must treat this like any other status failure — warn and continue with transcript-derived data — never fail the hook.
Functions ¶
func EnvWithoutRepoOverrides ¶ added in v0.10.3
func EnvWithoutRepoOverrides() []string
EnvWithoutRepoOverrides returns the current environment minus git's repo-selector variables (GIT_DIR, GIT_WORK_TREE, GIT_INDEX_FILE), so a git subprocess resolves its repository from cmd.Dir as the call site intends.
Use this for any git subprocess that can run inside a git hook and that names its target with cmd.Dir or `-C`. Inheriting these variables makes the child silently operate on the hook's repository instead: `git -C <other> rev-parse` reports the hook's repo, and an index-touching command reads and writes whatever GIT_INDEX_FILE names.
Deliberately not applied to user-invoked commands that operate on the current directory (`entire status`, `entire doctor`, `entire review`): there a GIT_DIR the user exported in their own shell is an instruction, not contamination.
func OpenCurrent ¶
func OpenCurrent(ctx context.Context) (*git.Repository, error)
OpenCurrent opens the current git worktree with object alternates enabled. The caller owns the returned repository and must close it.
A worktree root that will not resolve is an error, not a reason to open the current directory. This used to fall back to ".", which is a different repository whenever the two disagree, and go-git disagrees with git in exactly the cases that made the resolution fail:
- git exports GIT_DIR and GIT_WORK_TREE to the hooks it runs, and paths.WorktreeRoot honours them. OpenPath(".") cannot see them, so a hook running for repo A whose git lookup failed opened repo B, the unrelated repository it happened to be sitting in. Verified.
- git refuses a repository whose ownership fails its safe.directory check, and refuses a .git it cannot parse. go-git applies neither check, so the fallback opened repositories the user's own git declines to touch.
Five of the six callers write through the repository they are handed, and all five sit behind the root pre-run, which already refuses to run when the worktree root does not resolve — so this closes a trap rather than a live bug. The sixth is a best-effort advisory that genuinely wants the old behaviour and now asks for it by name: see OpenCurrentOrCwd.
func OpenCurrentOrCwd ¶ added in v0.10.4
func OpenCurrentOrCwd(ctx context.Context) (*git.Repository, error)
OpenCurrentOrCwd is OpenCurrent with the current directory as a fallback when the worktree root will not resolve.
It exists for one caller, WarnCheckpointPolicyIfNeeded, and the properties that make it acceptable there do not generalise: it is dispatched from main.go after cobra has finished, so unlike every other repository open it has no pre-run guard in front of it; it only READS a policy ref to decide whether to print an advisory line; and it discards every error it gets. Opening the wrong repository there costs a warning that is skipped or shown, not a write that lands in the wrong place.
Do not reach for this because OpenCurrent started returning an error. That error means Entire could not establish which repository this is, and for anything that writes, stopping is the whole point.
func OpenPath ¶
func OpenPath(repoRoot string) (*git.Repository, error)
OpenPath opens a git repository with object alternates enabled. The caller owns the returned repository and must close it.
func ResolveCommonGitPath ¶ added in v0.10.3
ResolveCommonGitPath resolves the shared Git directory for a resolved .git directory. An empty result means the repository has no commondir file.
func ResolveDotGitPath ¶ added in v0.10.3
ResolveDotGitPath resolves the .git entry for a worktree without opening the repository. Callers that need Git metadata should use this shared resolver.
func SetStatusBudgetBreachedForTesting ¶ added in v0.10.3
func SetStatusBudgetBreachedForTesting(breached bool)
SetStatusBudgetBreachedForTesting overrides the process-local breach latch so tests can exercise budget-breach degradation without a slow walk.
func Status ¶ added in v0.10.0
Status is the single entry point for reading go-git worktree status; the forbidigo rule in .golangci.yaml enforces this and names this signature, so the context parameter is part of that contract and is where cancellation or a perf span would attach.
Worktree.Status() walks the worktree, so its cost scales with working-set size rather than with the size of the change being inspected — it is the most expensive git read on the hook paths. Avoid calling it more than once per hook.
func StatusWithBudget ¶ added in v0.10.3
StatusWithBudget is Status bounded by StatusWalkBudget, for agent-hook capture paths. go-git's Worktree.Status is not context-cancellable, so on breach the walk goroutine is abandoned — it dies with the short-lived hook process, which is the point — and the returned error wraps ErrStatusBudgetExceeded so callers' warn-and-continue degrade paths apply. Paths where a user is actively waiting on a command (review via review_target.go, and `session adopt` via detectFileChangesUnbounded) keep calling Status directly.
Types ¶
This section is empty.
Source Files