Documentation
¶
Overview ¶
Package git provides a safe wrapper around git command execution.
This package delegates all git operations to the system git binary, leveraging the user's existing git configuration for authentication. It does not implement any platform-specific code (GitHub, GitLab, etc.) and does not store or manage credentials.
Key features:
- Command execution with proper stderr capture for error diagnostics
- Git version detection and validation (minimum: 2.5)
- Ref existence checking for local and remote repositories
- Repository state detection (shallow clone, git root)
- Structured error types with actionable messages
Example usage:
// Check if git is available
if !git.Available() {
return git.ErrGitNotFound
}
// Check git version
if err := git.CheckVersion(2, 5); err != nil {
return err
}
// Check if a ref exists locally
exists, err := git.RefExists("/path/to/repo", "main")
// Check if a ref exists in a remote repository
exists, err := git.RemoteRefExists("https://github.com/org/repo", "v1.0.0")
Index ¶
- Constants
- Variables
- func Available() bool
- func CheckMinVersion() error
- func CheckVersion(minMajor, minMinor int) error
- func CleanupOrphanedWorktrees(repoDir string)
- func FindGitRoot(dir string) (string, error)
- func GetCurrentBranch(dir string) (string, error)
- func GetHEAD(dir string) (string, error)
- func IsAuthError(err error) bool
- func IsGitRepository(dir string) bool
- func IsNotFound(err error) bool
- func IsShallowClone(dir string) (bool, error)
- func ListRemoteRefs(url string, patterns ...string) (map[string]string, error)
- func RefExists(dir, ref string) (bool, error)
- func RemoteRefExists(url, ref string) (bool, error)
- func ResolveRef(dir, ref string) (string, error)
- func ResolveRemoteRef(url, ref string) (sha string, fullRef string, err error)
- func Run(args []string, opts *RunOptions) (string, error)
- func RunSilent(args []string, opts *RunOptions) error
- func WorktreeList(repoDir string) ([]string, error)
- type Clone
- type ErrNotARepository
- type ErrRefNotFound
- type ErrVersionTooOld
- type GitError
- type RunOptions
- type Version
- type Worktree
Constants ¶
const ( MinVersionMajor = 2 MinVersionMinor = 5 )
MinVersion is the minimum git version required for tfbreak.
Variables ¶
var ErrGitNotFound = errors.New("git is not installed or not in PATH")
ErrGitNotFound is returned when git is not installed or not in PATH.
Functions ¶
func CheckMinVersion ¶
func CheckMinVersion() error
CheckMinVersion verifies git meets the minimum version for tfbreak.
func CheckVersion ¶
CheckVersion verifies git is installed and meets the minimum version requirement. Returns an error if git is not installed or version is below minMajor.minMinor.
func CleanupOrphanedWorktrees ¶
func CleanupOrphanedWorktrees(repoDir string)
CleanupOrphanedWorktrees removes any tfbreak worktrees that weren't properly cleaned up. This is a best-effort operation and errors are ignored.
func FindGitRoot ¶
FindGitRoot finds the root directory of the git repository containing dir. Returns the path to the repository root, or an error if dir is not in a git repository.
func GetCurrentBranch ¶
GetCurrentBranch returns the current branch name, or empty string if in detached HEAD state.
func IsAuthError ¶
IsAuthError returns true if the error indicates an authentication failure.
func IsGitRepository ¶
IsGitRepository returns true if dir is inside a git repository.
func IsNotFound ¶
IsNotFound returns true if the error indicates a ref was not found.
func IsShallowClone ¶
IsShallowClone returns true if the repository at dir is a shallow clone. A shallow clone has a .git/shallow file.
func ListRemoteRefs ¶
ListRemoteRefs lists all refs in a remote repository. If pattern is provided, only matching refs are returned.
func RefExists ¶
RefExists checks if a ref exists in a local repository. Returns true if the ref exists, false if it doesn't, or an error if the check fails.
func RemoteRefExists ¶
RemoteRefExists checks if a ref exists in a remote repository without cloning. This uses git ls-remote which only fetches ref information, not content.
func ResolveRef ¶
ResolveRef resolves a ref to its commit SHA in a local repository.
func ResolveRemoteRef ¶
ResolveRemoteRef resolves a ref to its commit SHA in a remote repository. Returns the SHA and the full ref name (e.g., "refs/tags/v1.0.0").
func Run ¶
func Run(args []string, opts *RunOptions) (string, error)
Run executes a git command and returns the stdout output. If the command fails, a *GitError is returned with stderr context.
func RunSilent ¶
func RunSilent(args []string, opts *RunOptions) error
RunSilent executes a git command without capturing output. It returns an error if the command fails.
func WorktreeList ¶
WorktreeList returns a list of all worktrees for the repository.
Types ¶
type Clone ¶
type Clone struct {
// Path is the filesystem path to the clone.
Path string
// URL is the repository URL that was cloned.
URL string
// Ref is the ref that was checked out.
Ref string
// SHA is the resolved commit SHA.
SHA string
}
Clone represents a shallow clone that will be cleaned up.
func CloneForComparison ¶
CloneForComparison creates two shallow clones for comparing two refs. Both clones are returned, and the caller is responsible for calling Remove() on both. If creating either clone fails, any created clone is cleaned up before returning.
func ShallowClone ¶
ShallowClone creates a shallow clone of a remote repository at a specific ref. The clone is created in a temporary directory and should be cleaned up by calling Remove() when done.
This uses --depth 1 --single-branch for efficiency, downloading only the necessary data for the specified ref.
type ErrNotARepository ¶
type ErrNotARepository struct {
Dir string
}
ErrNotARepository is returned when the directory is not inside a git repository.
func (*ErrNotARepository) Error ¶
func (e *ErrNotARepository) Error() string
type ErrRefNotFound ¶
ErrRefNotFound is returned when a ref doesn't exist.
func (*ErrRefNotFound) Error ¶
func (e *ErrRefNotFound) Error() string
type ErrVersionTooOld ¶
ErrVersionTooOld is returned when git version is below the minimum required.
func (*ErrVersionTooOld) Error ¶
func (e *ErrVersionTooOld) Error() string
type RunOptions ¶
type RunOptions struct {
// Dir is the working directory for the command.
// If empty, the current working directory is used.
Dir string
// Env contains additional environment variables.
// These are appended to the current environment.
Env []string
}
RunOptions configures how a git command is executed.
type Version ¶
Version represents a parsed git version.
func ParseVersion ¶
ParseVersion parses a git version string.
type Worktree ¶
type Worktree struct {
// Path is the filesystem path to the worktree.
Path string
// RepoDir is the path to the main repository.
RepoDir string
// Ref is the ref that was checked out.
Ref string
// SHA is the resolved commit SHA.
SHA string
}
Worktree represents a git worktree that will be cleaned up.
func CreateWorktree ¶
CreateWorktree creates a detached worktree at the specified ref. The worktree is created in a temporary directory and should be cleaned up by calling Remove() when done.
Source Files