git

Documentation

Index

• Variables
• func BareRepositorySHA(path, branch string) string
• func CheckoutSHA(localPath, sha string) error
• func CleanupRepository(path 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 CloneRepository(input string, verbose bool) (string, string, error)
• func ExpandShorthand(input string) string
• func ExpandShorthandSSH(input string) string
• func FindSetupFile(dir, path string) (string, error)
• func IsBareRepository(path string) bool
• func IsGitURL(input string) bool
• func LocalSHA(path string) string
• func LocalSHAWithError(path string) (string, error)
• func NormalizeGitURL(url string) string
• func RemoteHeadSHA(url, branch string) string
• func RemoteHeadSHAWithError(url, branch string) (string, error)
• func RepositoryStoragePath(url, branch string) (string, error)
• func StripBranch(input string) string
• type GitURLParams
  • func ParseGitURL(input string) GitURLParams

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 CleanupRepository

func CleanupRepository(path string) error

CleanupRepository removes the temporary repository directory

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 CloneRepository

func CloneRepository(input string, verbose bool) (string, string, error)

CloneRepository clones a git repository to a temporary directory and returns the path to the cloned repository Accepts URL with optional branch: url@branch or path: url:path or both: url@branch:path verbose: if true, shows clone progress; if false, hides progress output

func ExpandShorthand

func ExpandShorthand(input string) string

ExpandShorthand expands @provider:user/repo[@branch][:path] to a full HTTPS URL. Returns the input unchanged if it is not a shorthand form.

Examples:

@github:user/repo              → https://github.com/user/repo
@gitlab:user/repo@main         → https://gitlab.com/user/repo@main
@bitbucket:user/repo@v1:ci.bp  → https://bitbucket.org/user/repo@v1:ci.bp

func ExpandShorthandSSH

func ExpandShorthandSSH(input string) string

ExpandShorthandSSH expands @provider:user/repo[@branch][:path] to an SSH URL. Returns the input unchanged if it is not a shorthand form.

Examples:

@github:user/repo      → git@github.com:user/repo
@gitlab:user/repo@main → git@gitlab.com:user/repo@main

func FindSetupFile

func FindSetupFile(dir, path string) (string, error)

FindSetupFile looks for a setup file in the given directory If path is not provided, defaults to "setup.bp"

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 IsGitURL

func IsGitURL(input string) bool

IsGitURL checks if the given string is a git URL

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 NormalizeGitURL

func NormalizeGitURL(url string) string

NormalizeGitURL normalizes a git URL for consistent identification. It converts SSH URLs to HTTPS and lowercases the result.

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.

func RepositoryStoragePath

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

RepositoryStoragePath returns the local cache path for a blueprint repository. This is where `blueprint apply <git-url>` stores the cloned repo.

func StripBranch

func StripBranch(input string) string

StripBranch removes the @branch and :path specifiers from a git URL, returning just the base repository URL. This is useful for comparing whether two blueprint URLs point to the same repo regardless of branch.

Types

type GitURLParams

type GitURLParams struct {
	URL    string
	Branch string
	Path   string
}

GitURLParams holds parsed git URL information

func ParseGitURL

func ParseGitURL(input string) GitURLParams

ParseGitURL parses a git URL with optional branch and path.

Supported formats:

https://github.com/user/repo[@branch][:path/to/file.bp]
https://github.com/user/repo.git[@branch][:path/to/file.bp]
git@github.com:user/repo.git[@branch[:path/to/file.bp]]
git://github.com/user/repo.git[@branch][:path/to/file.bp]