git

func CreateWorktree ¶ added in v1.203.0

func CreateWorktree(repoDir, targetCommit string) (string, error)

CreateWorktree creates a new git worktree at the specified path, checked out to the given target ref or SHA. This uses `git worktree add --detach` to create an isolated worktree that shares the repository's object database but has its own HEAD, allowing checkout operations without affecting the main worktree. The repoDir should be the path to any directory in the repository (main worktree or any linked worktree). Returns the path to the created worktree directory.

func CreateWorktreeWithFetchRecovery ¶

func CreateWorktreeWithFetchRecovery(repoDir, targetCommit, targetBranch string) (string, error)

CreateWorktreeWithFetchRecovery creates a worktree at targetCommit, with a one-shot self-heal: if the initial CreateWorktree call fails because the target commit is missing from the local object DB AND a non-empty targetBranch is provided, the function performs a targeted `git fetch origin <targetBranch>` and retries.

This is the common shallow-clone CI scenario: actions/checkout@v4 with the default fetch-depth=1 only pulls the PR head, so a base SHA resolved from the GitHub event payload (event.pull_request.base.sha) often is not in the local object DB. A targeted fetch of the target branch is enough to make the SHA available without paying for a full unshallow.

Recovery is gated to ErrGitRefNotFound so that unrelated failures (temp directory creation, repo state corruption, permissions, etc.) propagate directly instead of being misdiagnosed as "target commit not available locally" and noisily attempting an unrelated fetch.

On final failure, the original CreateWorktree error is preserved (joined with the fetch error if the fetch also failed) so the caller can still surface its hints to the user.

func DeepenFetch ¶

func DeepenFetch(repoDir, branch string, depth int) error

DeepenFetch deepens a shallow clone by fetching additional history for a branch. Used as a second-stage fetch when the initial FetchRef succeeds but merge-base still cannot find a common ancestor (i.e., the fork point is older than the initial fetch depth).

Depth is the number of commits to deepen by, measured from the current shallow boundary. A value of 0 or negative means "fetch full history" (equivalent to --unshallow).

func EnsureGitSafeDirectory ¶ added in v1.215.0

func EnsureGitSafeDirectory() error

EnsureGitSafeDirectory adds GITHUB_WORKSPACE to git's safe.directory list when running in a GitHub Actions container. Container jobs run as a different user than the checkout owner, causing git to reject the repo as "dubious ownership".

func FetchRef ¶

func FetchRef(repoDir, branch string) error

FetchRef fetches a single branch from the "origin" remote using a narrow refspec. This minimizes data transfer compared to a full fetch, which is important for CI shallow clones where remote-tracking refs may not exist locally. The repoDir should be a path inside the repository.

func GetLocalRepo ¶

func GetLocalRepo() (*git.Repository, error)

func GetRepoConfig ¶

func GetRepoConfig(repo *git.Repository) (*config.Config, error)

func GetWorktreeParentDir ¶ added in v1.203.0

func GetWorktreeParentDir(worktreePath string) string

GetWorktreeParentDir returns the parent directory of a worktree path. This is useful for cleanup since CreateWorktree creates a parent temp dir containing the worktree.

func MergeBase ¶ added in v1.214.0

func MergeBase(repoDir, targetBranch string) (string, error)

MergeBase computes the common ancestor between HEAD and origin/<targetBranch> inside the repository at repoDir. This is the gold standard for determining the fork point of a PR branch, regardless of what commit is checked out or which merge strategy was used.

The repoDir argument is a path inside the target repository (the .git directory is auto-detected upward from this path). Use "." for the current working directory.

Returns an error if:

• the local repo cannot be opened
• origin/<targetBranch> does not exist (e.g., shallow checkout)
• no common ancestor exists between the two commits
• the merge-base equals HEAD (HEAD is on the target branch)

MergeBase is a pure read operation. It will not modify the local object database. Callers running in CI shallow checkouts should prefer MergeBaseWithAutoFetch, which transparently fetches the target branch and deepens history when needed.

func MergeBaseWithAutoFetch ¶

func MergeBaseWithAutoFetch(repoDir, targetBranch string) (string, error)

MergeBaseWithAutoFetch is a CI-aware wrapper around MergeBase that transparently recovers from shallow-clone failures by fetching the target branch and, if needed, deepening history.

RepoDir is a path inside the repository (used to scope the fetch).

Behavior:

1. Run MergeBase. If it succeeds, return the SHA.
2. If it fails because origin/<targetBranch> is not present locally, call FetchRef(repoDir, targetBranch) and retry MergeBase.
3. If MergeBase still returns ErrNoCommonAncestor (the shallow boundary does not reach the fork point), call DeepenFetch with deepenStep and retry once. This is bounded — we deepen at most once.
4. If recovery is impossible (no network, target branch does not exist remotely, etc.), return the original MergeBase error so the caller can fall through to its own fallback chain.

ErrHeadOnTargetBranch is propagated unchanged (no fetch can fix it).

func OpenWorktreeAwareRepo ¶ added in v1.191.0

func OpenWorktreeAwareRepo(path string) (*git.Repository, error)

OpenWorktreeAwareRepo opens a Git repository at the given path, handling both regular repositories and worktrees correctly. It uses EnableDotGitCommonDir to properly support worktrees with access to the main repository's config, remotes, and references.

func RemoveWorktree ¶ added in v1.203.0

func RemoveWorktree(repoDir, worktreePath string)

RemoveWorktree removes a git worktree using `git worktree remove`. This properly unregisters the worktree from git's tracking in addition to removing the directory. The repoDir parameter should be the path to any directory in the repository (main worktree or any linked worktree).