Documentation
¶
Overview ¶
Package git provides git-aware cache invalidation for Trace.
Description ¶
This package wraps git command execution to proactively invalidate the code graph cache when git operations change the working tree. It classifies commands by impact (full/targeted/none) and coordinates with the cache system to ensure stale data is never used.
Thread Safety ¶
GitAwareExecutor is safe for concurrent use.
Index ¶
- func IsWorktree(gitPath string) bool
- func ResolveWorktreeGitDir(gitPath string) (string, error)
- type CacheInvalidator
- type ExecuteResult
- type ExecutorConfig
- type GitAwareExecutor
- func (e *GitAwareExecutor) Execute(ctx context.Context, args ...string) (*ExecuteResult, error)
- func (e *GitAwareExecutor) ExecuteWithRebuild(ctx context.Context, rebuild bool, args ...string) (*ExecuteResult, error)
- func (e *GitAwareExecutor) FindGitDir(ctx context.Context) (string, error)
- func (e *GitAwareExecutor) GetCurrentBranch(ctx context.Context) (string, error)
- func (e *GitAwareExecutor) IsDetachedHead(ctx context.Context) bool
- type HeadWatcher
- type InvalidationType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsWorktree ¶
IsWorktree checks if the .git path is a worktree reference.
Description ¶
Git worktrees have a .git file (not directory) that points to the actual git directory. This affects where to watch for changes.
Inputs ¶
- gitPath: Path to .git (file or directory).
Outputs ¶
- bool: True if gitPath is a worktree reference file.
func ResolveWorktreeGitDir ¶
ResolveWorktreeGitDir resolves the actual .git directory for a worktree.
Description ¶
If the repository is a worktree, .git is a file containing a path to the actual git directory. This resolves that reference.
Inputs ¶
- gitPath: Path to .git file.
Outputs ¶
- string: Path to actual git directory.
- error: Non-nil if not a worktree or parse fails.
Types ¶
type CacheInvalidator ¶
type CacheInvalidator interface {
// InvalidateAll clears the entire cache.
// Called after full invalidation commands (checkout, merge, etc.)
InvalidateAll() error
// InvalidateFiles invalidates cache entries for specific files.
// Called after targeted invalidation commands (add, restore).
InvalidateFiles(paths []string) error
// WaitForRebuilds waits for any in-flight cache rebuilds to complete.
// Called before invalidation to avoid race conditions.
WaitForRebuilds() error
}
CacheInvalidator is the interface for cache invalidation.
Description ¶
Implemented by the graph cache to allow git executor to trigger invalidation after commands that modify the working tree.
type ExecuteResult ¶
type ExecuteResult struct {
Output string
ExitCode int
InvalidationType InvalidationType
FilesInvalidated []string
}
ExecuteResult contains the outcome of a git command execution.
Description ¶
Returned by GitAwareExecutor.Execute with command output and information about cache invalidation performed.
Fields ¶
- Output: Combined stdout/stderr from the git command.
- ExitCode: Process exit code (0 = success).
- InvalidationType: What kind of cache invalidation was performed.
- FilesInvalidated: For targeted invalidation, which files were affected.
type ExecutorConfig ¶
type ExecutorConfig struct {
WorkDir string
Cache CacheInvalidator
InvalidationTimeout int // seconds, default 30
}
ExecutorConfig configures the GitAwareExecutor behavior.
Description ¶
Allows customization of working directory and invalidation behavior.
Fields ¶
- WorkDir: Git repository root directory.
- Cache: Cache invalidator (may be nil to skip invalidation).
- InvalidationTimeout: Max time to wait for cache rebuilds before forcing invalidation.
func DefaultExecutorConfig ¶
func DefaultExecutorConfig() ExecutorConfig
DefaultExecutorConfig returns a config with sensible defaults.
type GitAwareExecutor ¶
type GitAwareExecutor struct {
// contains filtered or unexported fields
}
GitAwareExecutor executes git commands with automatic cache invalidation.
Description ¶
Wraps git command execution to proactively invalidate the code graph cache when operations change the working tree. Commands are classified by impact and appropriate invalidation is performed after successful execution.
Thread Safety ¶
All methods are safe for concurrent use.
func NewGitAwareExecutor ¶
func NewGitAwareExecutor(config ExecutorConfig) (*GitAwareExecutor, error)
NewGitAwareExecutor creates a new git executor with cache invalidation.
Description ¶
Creates an executor that will invalidate the provided cache after git commands that modify the working tree.
Inputs ¶
- config: Executor configuration.
Outputs ¶
- *GitAwareExecutor: Ready-to-use executor.
- error: Non-nil if configuration is invalid.
func (*GitAwareExecutor) Execute ¶
func (e *GitAwareExecutor) Execute(ctx context.Context, args ...string) (*ExecuteResult, error)
Execute runs a git command and invalidates cache as needed.
Description ¶
Executes the git command, then performs appropriate cache invalidation based on the command type. Invalidation only happens if the command succeeds (exit code 0).
Inputs ¶
- ctx: Context for command timeout and cancellation.
- args: Git command arguments (e.g., "checkout", "main").
Outputs ¶
- *ExecuteResult: Command output and invalidation info.
- error: Non-nil on execution failure.
Example ¶
result, err := executor.Execute(ctx, "checkout", "feature-branch")
if err != nil {
return err
}
fmt.Println(result.Output)
// Cache was automatically invalidated (InvalidationFull)
func (*GitAwareExecutor) ExecuteWithRebuild ¶
func (e *GitAwareExecutor) ExecuteWithRebuild(ctx context.Context, rebuild bool, args ...string) (*ExecuteResult, error)
ExecuteWithRebuild runs a git command and optionally triggers cache rebuild.
Description ¶
Like Execute, but after invalidation can trigger an immediate rebuild of the cache rather than waiting for the next query.
Inputs ¶
- ctx: Context for command timeout.
- rebuild: If true, trigger immediate cache rebuild after invalidation.
- args: Git command arguments.
Outputs ¶
- *ExecuteResult: Command output and invalidation info.
- error: Non-nil on failure.
func (*GitAwareExecutor) FindGitDir ¶
func (e *GitAwareExecutor) FindGitDir(ctx context.Context) (string, error)
FindGitDir returns the .git directory for the working directory.
Description ¶
Uses `git rev-parse --git-dir` to find the correct .git directory, handling worktrees and GIT_DIR environment variable.
Inputs ¶
- ctx: Context for command timeout.
Outputs ¶
- string: Path to .git directory.
- error: Non-nil if not a git repository.
func (*GitAwareExecutor) GetCurrentBranch ¶
func (e *GitAwareExecutor) GetCurrentBranch(ctx context.Context) (string, error)
GetCurrentBranch returns the current branch name.
Description ¶
Returns the current branch name, or "HEAD" if detached.
Inputs ¶
- ctx: Context for command timeout.
Outputs ¶
- string: Branch name or "HEAD".
- error: Non-nil if not a git repository.
func (*GitAwareExecutor) IsDetachedHead ¶
func (e *GitAwareExecutor) IsDetachedHead(ctx context.Context) bool
IsDetachedHead checks if the repository is in detached HEAD state.
Description ¶
Uses `git symbolic-ref HEAD` which fails if HEAD is detached.
Inputs ¶
- ctx: Context for command timeout.
Outputs ¶
- bool: True if HEAD is detached.
type HeadWatcher ¶
type HeadWatcher struct {
// contains filtered or unexported fields
}
HeadWatcher watches for changes to .git/HEAD (branch switches).
Description ¶
Detects when the repository HEAD changes (e.g., via external git checkout from another terminal). Triggers cache invalidation when detected.
Thread Safety ¶
Safe for concurrent use. Start should only be called once.
func NewHeadWatcher ¶
func NewHeadWatcher(gitDir string, cache CacheInvalidator, callback func()) (*HeadWatcher, error)
NewHeadWatcher creates a watcher for git HEAD changes.
Description ¶
Creates a watcher that monitors .git/HEAD and invokes the callback when changes are detected. The callback should invalidate the cache.
Inputs ¶
- gitDir: Path to .git directory.
- cache: Cache invalidator (may be nil).
- callback: Optional callback on HEAD change (in addition to cache invalidation).
Outputs ¶
- *HeadWatcher: Ready-to-start watcher.
- error: Non-nil if watcher creation fails.
func (*HeadWatcher) Start ¶
func (w *HeadWatcher) Start(ctx context.Context)
Start begins watching for HEAD changes.
Description ¶
Watches .git/HEAD and related files for changes. Blocks until context is cancelled. Should be run in a goroutine.
Inputs ¶
- ctx: Context for cancellation.
Example ¶
watcher, _ := git.NewHeadWatcher(gitDir, cache, nil) go watcher.Start(ctx)
func (*HeadWatcher) Stop ¶
func (w *HeadWatcher) Stop() error
Stop stops the watcher.
Description ¶
Stops watching and releases resources. Safe to call multiple times.
type InvalidationType ¶
type InvalidationType int
InvalidationType indicates how much of the cache should be invalidated.
const ( // InvalidationNone means the command doesn't affect the working tree. // Examples: git status, git diff, git log, git show InvalidationNone InvalidationType = iota // InvalidationTargeted means specific files changed. // Examples: git add <files>, git restore <files>, git checkout -- <files> InvalidationTargeted // InvalidationFull means the entire working tree may have changed. // Examples: git checkout <branch>, git merge, git pull, git reset --hard InvalidationFull )
func (InvalidationType) String ¶
func (t InvalidationType) String() string
String returns a human-readable name for the invalidation type.
Source Files