gitctx

Documentation

Overview

Package gitctx reads a cwd's git state for the prompt builder's dynamic context section.

Design choices:

• Subprocess only (no go-git). Reuses the user's installed git binary, so behavior matches what the user sees on the CLI.
• Read-only. Never invokes `git add`, `commit`, or any mutating operation.
• Failure-tolerant. A missing git binary, a non-repo cwd, or any individual command failure returns a partial Snapshot with a nil error — git context is advisory, not load-bearing.

Index

• type Reader
  • func (r *Reader) Read(ctx context.Context) (Snapshot, error)
• type Snapshot

Types

type Reader

type Reader struct {
	CWD      string
	Timeout  time.Duration
	CacheTTL time.Duration
	// contains filtered or unexported fields
}

Reader reads git state from a cwd. Construct directly; the zero value with a populated CWD is usable (defaultTimeout + defaultCacheTTL apply).

Within CacheTTL of a successful Read, subsequent Reads return the cached Snapshot without reinvoking git — the agent calls Read on every turn, but git status / diff over the same working tree rarely change that fast and forking git per turn is wasteful. Failed Reads are not cached so the next call retries.

func (*Reader) Read

func (r *Reader) Read(ctx context.Context) (Snapshot, error)

Read collects the snapshot. Each git command is bounded by the shorter of ctx and r.Timeout (defaults to 2s). Snapshots from successful Reads are cached for CacheTTL (defaults to 5s).

Errors are returned only when the cwd itself is malformed (e.g. the directory doesn't exist). Individual git command failures are swallowed — the corresponding Snapshot fields stay empty.

type Snapshot

type Snapshot struct {
	Status        string   // git status --short, truncated
	Diff          string   // staged + unstaged --stat, combined and truncated
	ActiveBranch  string   // git rev-parse --abbrev-ref HEAD
	RecentCommits []string // git log -3 --oneline
}

Snapshot is one read of the cwd's git state. All fields are optional — a non-git cwd yields a zero-value Snapshot with nil error.