git

Documentation

Overview

Package git wraps the user's local `git` CLI for diff extraction.

We deliberately shell out instead of using a Go git library:

• The user's repo state already works with their git binary (config, hooks, signatures, etc.).
• Pulling in go-git would balloon the binary by ~10MB.

Index

• func CurrentBranch() string
• func CurrentCommit() string
• func RepoRoot() (string, error)
• func ResolveRef(ref string) string
• func SanitizeBranchName(branch string) string
• func SanitizeCommit(commit string) string
• func TrackedFiles(root string) ([]string, error)
• func ValidateRef(ref string) error
• type Diff
  • func Extract(ctx context.Context, mode Mode, ref string) ([]Diff, error)
• type Hunk
• type Mode

Functions

func CurrentBranch

func CurrentBranch() string

CurrentBranch returns the current branch name. Returns "unknown" if git command fails or times out (e.g., detached HEAD).

func CurrentCommit

func CurrentCommit() string

func RepoRoot

func RepoRoot() (string, error)

RepoRoot returns the absolute path to the repository's top level via `git rev-parse --show-toplevel`. Used by the audit subcommand to resolve git-relative paths (which `git ls-files` returns) against the actual repo root rather than the user's current working directory — running `local-review audit` from a subdirectory would otherwise try to read paths against the subdir and fail.

Returns an error when not inside a git working tree, matching git's own exit-non-zero behaviour. Callers should treat that the same as TrackedFiles failing.

func ResolveRef

func ResolveRef(ref string) string

ResolveRef resolves a git ref (branch name, tag, short hash) to a full commit hash. Returns the first 7 characters of the commit hash, or empty string if resolution fails / times out / the ref is rejected by ValidateRef (refs starting with `-` would otherwise be parsed by git as flags).

func SanitizeBranchName

func SanitizeBranchName(branch string) string

SanitizeBranchName replaces characters that are unsafe for filesystem paths. Replaces / with - to handle branch names like "feature/auth-fix".

func SanitizeCommit

func SanitizeCommit(commit string) string

SanitizeCommit removes any characters that aren't valid in git commit hashes. Only allows [a-fA-F0-9-] to prevent path traversal via commit parameters.

func TrackedFiles

func TrackedFiles(root string) ([]string, error)

TrackedFiles returns every git-tracked file under the current working tree, one path per element, relative to the repo root. Used by the audit subcommand to enumerate source the LLM should scan — git's view (excludes .gitignore'd build artifacts, vendor caches, .env, etc.) is exactly the "code we ship" surface the audit cares about.

Output ordering is git's: paths in tree order, deterministic across invocations on the same commit. Caller groups by directory for chunking; see internal/audit/walker.go.

Returns an empty slice (not nil) when the repo has no tracked files — same shape as `git ls-files` with empty stdout. An empty repo is a real edge case (just-`git init`'d project); the audit runner reports "nothing to scan" rather than crashing.

Shells out via `os/exec` for the same reason internal/git/diff.go does: keeps the binary go-git-free per the project's hard constraints (CLAUDE.md "What this project is" section).

func ValidateRef

func ValidateRef(ref string) error

ValidateRef rejects user-supplied git refs that could be parsed by git as command-line flags rather than refs. A ref starting with `-` (e.g., `--output=/tmp/xyz`, `-c core.editor=...`) would be treated as a flag in `git diff <ref>...HEAD` or `git show <ref>` despite looking like a positional argument, so we refuse anything that shape rather than relying on a `--` separator that doesn't apply uniformly across git subcommands.

We also reject refs containing newlines or NUL bytes because they can't survive a shell pipeline correctly and almost always indicate caller bugs (or attempted injection from a wrapping script).

Types

type Diff

type Diff struct {
	Path  string
	Hunks []Hunk
}

Diff is a single diffed file with its hunks.

func Extract

func Extract(ctx context.Context, mode Mode, ref string) ([]Diff, error)

Extract runs git and returns one Diff per changed file.

args:

ctx:  cancellation / deadline (the runner threads its signal-trapped ctx)
mode: which slice of history
ref:  for ModeCommit, the revspec; for ModeBranch, the *base* ref to diff against

type Hunk

type Hunk struct {
	Header  string // raw "@@ -1,2 +1,3 @@" line
	Content string // body of the hunk (lines prefixed with +, -, space)
	NewFrom int    // first line number in new file
}

type Mode

type Mode int

Mode says which slice of history we want to review.

const (
	// ModeStaged: `git diff --cached` — what would be committed next.
	ModeStaged Mode = iota
	// ModeCommit: a single commit (revspec like HEAD or a SHA).
	ModeCommit
	// ModeBranch: full diff of a branch against a base ref.
	ModeBranch
)