git

Documentation

Index

• Variables
• func BareRepositorySHA(path, branch string) string
• func CheckoutSHA(localPath, sha string) error
• func CloneOrUpdateRepository(url, path, branch string) (string, string, string, error)
• func CloneOrUpdateRepositoryBare(url, targetPath, branch string) (string, string, string, error)
• func CloneOrUpdateRepositoryDirect(url, targetPath, branch string) (string, string, string, error)
• func CloneOrUpdateRepositoryDirectWithNotes(url, targetPath, branch string) (string, string, string, []string, error)
• func IsBareRepository(path string) bool
• func LocalSHA(path string) string
• func LocalSHAWithError(path string) (string, error)
• func RemoteHeadSHA(url, branch string) string
• func RemoteHeadSHAWithError(url, branch string) (string, error)

Variables

var CloneOrUpdateRepositoryTwoStage = cloneOrUpdateRepositoryTwoStageImpl

CloneOrUpdateRepositoryTwoStage variable for test stubbing

var GetCleanRepositorySHA = func(url, branch string) string {
	storagePath, err := getRepositoryStoragePath(url, branch)
	if err != nil {
		return ""
	}
	sha, _ := gitSHA(storagePath)
	return sha
}

GetCleanRepositorySHA returns the SHA of a repository from clean storage Made as a variable for test stubbing

Functions

func BareRepositorySHA

func BareRepositorySHA(path, branch string) string

BareRepositorySHA returns the SHA a bare (worktree) clone at path is synced to, for the given branch ("" for the remote default). It is the value to compare against the remote HEAD to decide whether the clone is current.

func CheckoutSHA

func CheckoutSHA(localPath, sha string) error

CheckoutSHA checks out a specific commit SHA in the repository at localPath. This is used by `blueprint doctor` to inspect the exact version that was applied.

func CloneOrUpdateRepository

func CloneOrUpdateRepository(url, path, branch string) (string, string, string, error)

CloneOrUpdateRepository clones a repository to a specific path or updates it if already exists. Tries go-git first; falls back to the system git binary if go-git fails (e.g. SSH agent issues). Returns: (oldSHA, newSHA, status_message, error) status_message can be: "Cloned", "Updated", "Already up to date"

Recoverable incidents (e.g. #031 untracked-file protection) are dropped here; callers that need them use the notes-aware core via CloneOrUpdateRepositoryDirectWithNotes.

func CloneOrUpdateRepositoryBare

func CloneOrUpdateRepositoryBare(url, targetPath, branch string) (string, string, string, error)

CloneOrUpdateRepositoryBare clones url as a bare repository into <targetPath>/.git and checks out branch (or the remote default branch) as a worktree at <targetPath>/<branch>. This is the layout git worktree managers such as worktrunk expect: the bare repository holds no working tree, so every branch — including the default — is a linked worktree at an equal path:

targetPath/
├── .git/    # bare repository
├── main/    # default branch worktree
└── feature/ # feature branch worktree

Later runs fetch into the bare repository so new branches and commits become visible to `wt switch`, and recreate the branch worktree if it is missing. Existing worktrees are never reset — they may hold uncommitted work.

The reported SHA is the tip of the tracked remote branch, not the bare repository's HEAD: a fetch only advances refs/remotes/origin/*, because moving refs/heads/<branch> would yank the branch out from under whichever worktree has it checked out.

Returns (oldSHA, newSHA, status, error) — same contract as CloneOrUpdateRepository.

func CloneOrUpdateRepositoryDirect

func CloneOrUpdateRepositoryDirect(url, targetPath, branch string) (string, string, string, error)

CloneOrUpdateRepositoryDirect clones url into targetPath preserving the .git directory, making it a fully functional working copy. When the directory already exists it does a git pull (fast-forward only) instead of re-cloning. Returns (oldSHA, newSHA, status, error) — same contract as CloneOrUpdateRepository.

func CloneOrUpdateRepositoryDirectWithNotes

func CloneOrUpdateRepositoryDirectWithNotes(url, targetPath, branch string) (string, string, string, []string, error)

CloneOrUpdateRepositoryDirectWithNotes is CloneOrUpdateRepositoryDirect plus the notes channel: recoverable incidents (e.g. #031 untracked-file protection warnings) surfaced through the GitProvider seam's CloneResult.Notes. The ModeDirect data-safety contract — untracked files MUST survive — is enforced on this path.

func IsBareRepository

func IsBareRepository(path string) bool

IsBareRepository reports whether path holds a bare git repository. Bare (worktree) clones keep their repository in <clone path>/.git, so this is how a clone rule recognises that layout on disk — including uninstall rules, which are rebuilt from status and don't carry the bare flag.

func LocalSHA

func LocalSHA(path string) string

LocalSHA reads the HEAD SHA of a local repository at the given path using go-git. Returns empty string if the path is not a valid git repository.

func LocalSHAWithError

func LocalSHAWithError(path string) (string, error)

LocalSHAWithError reads the HEAD SHA of a local repository, returning any error encountered.

func RemoteHeadSHA

func RemoteHeadSHA(url, branch string) string

RemoteHeadSHA returns the SHA of the remote HEAD (or branch tip) for the given URL and branch. Returns empty string if the check fails (network unavailable, auth issue, etc.).

func RemoteHeadSHAWithError

func RemoteHeadSHAWithError(url, branch string) (string, error)

RemoteHeadSHAWithError returns the remote HEAD SHA, propagating any error to the caller.