git

Documentation

Overview

Package git provides git operations including worktree management.

Package git provides git operations including worktree management.

Index

• func AddRemote(repoDir, name, url string) error
• func FetchBaseRef(repoRoot, remote, baseRef string) error
• func FetchBranch(ctx context.Context, repoDir, remote, branch string) error
• func GetCommonDir() (string, error)
• func GetDiff(ctx context.Context, baseRef, workDir string) (string, error)
• func GetRoot() (string, error)
• func IsLikelyCommitSHA(ref string) bool
• func IsRelativeRef(ref string) bool
• func IsTag(ctx context.Context, ref, workDir string) bool
• func PruneStaleWorktrees() error
• func QualifyBaseRef(remote, baseRef string) string
• func RemoveRemote(repoDir, name string) error
• func ShouldQualifyBaseRef(baseRef string, autoDetected bool) bool
• type FetchResult
  • func FetchRemoteRef(ctx context.Context, baseRef, workDir string) FetchResult
• type UpdateBranchResult
  • func UpdateCurrentBranch(ctx context.Context, workDir string) UpdateBranchResult
• type Worktree
  • func CreateWorktree(branch string) (*Worktree, error)
  • func CreateWorktreeFromPR(repoRoot, remote, prNumber string) (*Worktree, error)
  • func (w *Worktree) Remove() error

Functions

func AddRemote

func AddRemote(repoDir, name, url string) error

AddRemote adds a new git remote.

func FetchBaseRef

func FetchBaseRef(repoRoot, remote, baseRef string) error

FetchBaseRef fetches a base ref (e.g., "main") from the specified remote. This ensures the base ref exists locally for diff operations in PR worktrees. The ref is fetched as remote/base (e.g., origin/main) which can be used directly in git diff commands.

func FetchBranch

func FetchBranch(ctx context.Context, repoDir, remote, branch string) error

FetchBranch fetches a specific branch from a remote.

func GetCommonDir

func GetCommonDir() (string, error)

GetCommonDir returns the git common directory (shared across worktrees).

func GetDiff

func GetDiff(ctx context.Context, baseRef, workDir string) (string, error)

GetDiff returns the git diff against the specified base reference. If workDir is empty, uses the current directory. The context is used to support cancellation/timeout.

Note: For remote refs, call FetchRemoteRef once upfront before launching parallel reviewers to ensure all reviewers use the same ref for comparison.

func GetRoot

func GetRoot() (string, error)

GetRoot returns the root directory of the current git repository.

func IsLikelyCommitSHA

func IsLikelyCommitSHA(ref string) bool

IsLikelyCommitSHA returns true if the ref looks like a git commit SHA. We check for hex strings of 7-40 characters (short and full SHAs).

func IsRelativeRef

func IsRelativeRef(ref string) bool

IsRelativeRef returns true if the ref is relative to HEAD (e.g., HEAD, HEAD~3, main^2), a reflog ref (e.g., HEAD@{1}), or a commit SHA. These refs would change meaning if the branch is fast-forwarded, so the branch should not be updated when using them.

func IsTag

func IsTag(ctx context.Context, ref, workDir string) bool

IsTag checks if the given ref is a tag in the repository. Tags are stored in refs/tags/ and should not be prefixed with origin/.

func PruneStaleWorktrees

func PruneStaleWorktrees() error

PruneStaleWorktrees removes ACR-created worktrees older than staleWorktreeAge. Only removes directories matching the "review-*" naming convention under .worktrees/. Also runs "git worktree prune" to clean up git's internal bookkeeping.

func QualifyBaseRef

func QualifyBaseRef(remote, baseRef string) string

QualifyBaseRef returns a remote-qualified ref (e.g., "origin/main") for use in diff. If the ref is already qualified with the given remote, it's returned as-is.

func RemoveRemote

func RemoveRemote(repoDir, name string) error

RemoveRemote removes a git remote.

func ShouldQualifyBaseRef

func ShouldQualifyBaseRef(baseRef string, autoDetected bool) bool

ShouldQualifyBaseRef returns true if the base ref should be qualified with a remote prefix. The autoDetected parameter indicates whether the ref was auto-detected from a PR (always an unqualified branch name) vs explicitly set by the user (may be SHA, tag, or qualified ref).

When autoDetected is true, always returns true (PR base refs are always unqualified branches). When autoDetected is false, returns false for: - Already qualified refs (e.g., origin/main) - Commit SHAs (hex strings of 7+ chars) - Tags (v-prefixed, semver, or date-based patterns) - HEAD and HEAD-relative refs - Refs containing "/" (ambiguous - could be branch or qualified ref)

Types

type FetchResult

type FetchResult struct {
	// ResolvedRef is the ref to use for diffing (either "origin/<baseRef>" or "<baseRef>")
	ResolvedRef string
	// RefResolved indicates whether the ref was successfully resolved (true if fetch succeeded or was skipped)
	RefResolved bool
	// FetchAttempted indicates whether a fetch was attempted (false if baseRef already has origin/ prefix or is a non-branch ref)
	FetchAttempted bool
}

FetchResult contains the result of a FetchRemoteRef operation.

func FetchRemoteRef

func FetchRemoteRef(ctx context.Context, baseRef, workDir string) FetchResult

FetchRemoteRef fetches the base ref from origin and returns the resolved ref to use. If fetch succeeds, returns "origin/<baseRef>". If fetch fails, returns "<baseRef>". This function should be called once before launching parallel reviewers to ensure all reviewers use the same ref for comparison.

For non-branch refs (relative refs like HEAD~3, commit SHAs, or refs starting with -), the function skips fetching and returns the ref as-is since these cannot be fetched from a remote or would be invalid with the origin/ prefix.

type UpdateBranchResult

type UpdateBranchResult struct {
	BranchName     string // Current branch name (empty if detached)
	Updated        bool   // Whether the branch was fast-forwarded
	AlreadyCurrent bool   // Whether the branch was already up to date
	Skipped        bool   // Whether the update was skipped (detached HEAD, no remote, etc.)
	SkipReason     string // Why it was skipped
	Error          error  // Non-fatal error (fetch/merge failed)
}

UpdateBranchResult contains the result of an UpdateCurrentBranch operation.

func UpdateCurrentBranch

func UpdateCurrentBranch(ctx context.Context, workDir string) UpdateBranchResult

UpdateCurrentBranch fast-forwards the current branch from origin. This ensures the working tree has the latest commits before reviewing. All failures are non-fatal — the review continues with local state.

type Worktree

type Worktree struct {
	Path string
	// contains filtered or unexported fields
}

Worktree represents a git worktree with a path.

func CreateWorktree

func CreateWorktree(branch string) (*Worktree, error)

CreateWorktree creates a temporary worktree for the given branch. The caller is responsible for calling Remove() on the returned Worktree.

func CreateWorktreeFromPR

func CreateWorktreeFromPR(repoRoot, remote, prNumber string) (*Worktree, error)

CreateWorktreeFromPR fetches a PR and creates a detached worktree for it. The remote parameter specifies which remote to fetch from (e.g., "origin"). The worktree is created in detached HEAD mode from FETCH_HEAD, avoiding conflicts with existing local branches. The caller is responsible for calling Remove() on the returned Worktree.

func (*Worktree) Remove

func (w *Worktree) Remove() error

Remove cleans up the worktree.