git

Documentation

Overview

Package git provides git tool factories and shell-out helpers that agents can register without re-implementing PATH lookup, timeout management, or pathspec construction.

The package is intentionally outside the core glue package so the harness stays free of POSIX coupling per ADR 0003. RunGit shells out to the system `git` binary; importing this package does not pull in a Git library.

Index

• Constants
• func BuildPathspec(includes, excludes []string) []string
• func DiffBranchTool(opts DiffBranchOptions) glue.Tool
• func LogBranchTool(opts LogBranchOptions) glue.Tool
• func RunGit(ctx context.Context, opts RunOptions, args ...string) (string, error)
• type DiffBranchOptions
• type LogBranchOptions
• type RunOptions

Constants

const DefaultDiffMaxBytes = 200 * 1024

DefaultDiffMaxBytes caps the diff returned by DiffBranchTool when the model does not request a smaller cap.

const DefaultLogLimit = 50

DefaultLogLimit caps the commit count returned by LogBranchTool when the model does not request a smaller limit.

const DefaultRunTimeout = 15 * time.Second

DefaultRunTimeout caps a single git invocation. Override per-call via RunOptions.Timeout when a long-running operation is expected.

Functions

func BuildPathspec

func BuildPathspec(includes, excludes []string) []string

BuildPathspec converts include / exclude glob lists into Git pathspec arguments. The Git CLI accepts:

• bare patterns as include filters (e.g. `*.go`, `cmd/...`)
• `:(exclude)pattern` as exclude filters

Excludes only take effect after at least one include pattern is present, so when callers pass only excludes we add `*` as an explicit catch-all include — matching the intuitive "review everything except X" semantics.

Returns nil when both lists are empty so callers can branch on len(out) > 0 to decide whether to emit a `--` separator.

func DiffBranchTool

func DiffBranchTool(opts DiffBranchOptions) glue.Tool

DiffBranchTool returns a glue.Tool named "git_diff_branch" that runs `git diff --no-color <base>...HEAD` in opts.WorkDir, optionally pathspec-filtered. Errors surface as error ToolResults so the model can recover.

func LogBranchTool

func LogBranchTool(opts LogBranchOptions) glue.Tool

LogBranchTool returns a glue.Tool named "git_log_branch" that runs `git log --no-color -n<limit> <base>..HEAD` with a stable pretty-format. Useful for reading commit messages to understand author intent.

func RunGit

func RunGit(ctx context.Context, opts RunOptions, args ...string) (string, error)

RunGit invokes the system `git` binary in opts.WorkDir with the given arguments. Stdout is returned on success; on failure the returned error includes the command line and trimmed stderr so callers can surface a useful message to the model.

Types

type DiffBranchOptions

type DiffBranchOptions struct {
	// WorkDir is the git repo to diff in. Required.
	WorkDir string

	// Pathspec is appended after `--`; build with BuildPathspec from
	// deployment-supplied include/exclude globs. Empty means "all
	// changed files".
	Pathspec []string

	// DefaultBase is used when the tool call does not specify `base`.
	// Empty falls back to "main".
	DefaultBase string

	// MaxBytes caps the returned diff. Zero falls back to
	// DefaultDiffMaxBytes.
	MaxBytes int

	// Timeout caps a single git invocation. Zero falls back to
	// DefaultRunTimeout from RunGit.
	Timeout time.Duration
}

DiffBranchOptions configures DiffBranchTool.

type LogBranchOptions

type LogBranchOptions struct {
	// WorkDir is the git repo to read commits from. Required.
	WorkDir string

	// DefaultBase is used when the tool call does not specify `base`.
	// Empty falls back to "main".
	DefaultBase string

	// DefaultLimit is used when the tool call does not specify `limit`.
	// Zero falls back to DefaultLogLimit.
	DefaultLimit int

	// Timeout caps a single git invocation. Zero falls back to
	// DefaultRunTimeout from RunGit.
	Timeout time.Duration
}

LogBranchOptions configures LogBranchTool.

type RunOptions

type RunOptions struct {
	// WorkDir is the cwd for the git invocation. Required.
	WorkDir string

	// Timeout caps a single invocation. Zero falls back to
	// DefaultRunTimeout.
	Timeout time.Duration
}

RunOptions configures RunGit.