git

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package git provides git operations via shell commands.

All operations use os/exec.Command to call the git CLI directly rather than using Go git libraries. This approach is simpler, more reliable, and ensures compatibility with user configurations (SSH keys, credential helpers, aliases).

Worktree Operations

Core worktree management:

Repository Operations

Repository and branch queries:

Repository Discovery

Finding repositories by name or label:

Git worktrees have bidirectional links between the worktree's .git file and the main repo's .git/worktrees/ directory. These can break when repos are moved. Functions for diagnosis and repair:

Batching for Performance

ListWorktrees uses batched git calls to minimize subprocess overhead: one "git worktree list --porcelain" per repo instead of individual calls per worktree. For 10 worktrees across 2 repos, this reduces calls from ~40 to ~8 (or ~18 with dirty checks enabled).

Index

Constants

This section is empty.

Variables

View Source 
var ErrGitNotFound = fmt.Errorf("git not found: please install git (https://git-scm.com)")

ErrGitNotFound indicates git is not installed or not in PATH

Functions

func AddLabel 

func AddLabel(repoPath, label string) error

AddLabel adds a label to a repository (if not already present)

func BranchExists 

func BranchExists(branch string) (bool, error)

BranchExists checks if a local branch exists

func CanRepairWorktree added in v0.4.0 

func CanRepairWorktree(worktreePath string) bool

CanRepairWorktree checks if a worktree can potentially be repaired. Returns true if .git file exists but links are broken.

func CheckGit 

func CheckGit() error

CheckGit verifies that git is available in PATH

func ClearBranchNote 

func ClearBranchNote(repoPath, branch string) error

ClearBranchNote removes the note (description) from a branch

func ClearLabels 

func ClearLabels(repoPath string) error

ClearLabels removes all labels from a repository

func DeleteLocalBranch 

func DeleteLocalBranch(repoPath, branch string, force bool) error

DeleteLocalBranch deletes a local branch

func ExtractRepoNameFromURL 

func ExtractRepoNameFromURL(url string) string

ExtractRepoNameFromURL extracts the repository name from a git URL

func FetchBranch 

func FetchBranch(repoPath, branch string) error

FetchBranch fetches a specific branch from origin

func FetchDefaultBranch 

func FetchDefaultBranch(repoPath string) error

FetchDefaultBranch fetches the default branch (main/master) from origin

func FindAllRepos 

func FindAllRepos(basePath string) ([]string, error)

FindAllRepos returns paths to all git repositories in basePath (direct children only)

func FindRepoByName 

func FindRepoByName(basePath, name string) (string, error)

FindRepoByName searches direct children of basePath for a git repo with the given name. First checks for exact folder name match with matching origin, then searches all repos by origin. Returns the full path if found, or an error if not found.

func FindRepoInDirs added in v0.6.0 

func FindRepoInDirs(repoName string, searchDirs ...string) string

FindRepoInDirs searches for a repo with the given name in the provided directories. Returns the absolute path to the repo if found, empty string otherwise. Unlike FindRepoByName in discovery.go, this checks multiple directories and only looks for exact folder name matches with a valid .git directory.

func FindReposByLabel 

func FindReposByLabel(scanDir, label string) ([]string, error)

FindReposByLabel scans a directory for repos with the given label Returns paths to matching repositories

func FindSimilarRepos 

func FindSimilarRepos(basePath, search string) []string

FindSimilarRepos returns repo names in basePath that contain the search string. Useful for providing suggestions when a repo is not found.

func GetAllBranchConfig 

func GetAllBranchConfig(repoPath string) (notes map[string]string, upstreams map[string]bool)

GetAllBranchConfig returns branch notes and upstreams for a repository in one call. Uses: `git config --get-regexp 'branch\.'` Returns: notes map (branch -> note), upstreams map (branch -> upstream ref)

func GetBranchCreatedTime 

func GetBranchCreatedTime(repoPath, branch string) (time.Time, error)

GetBranchCreatedTime returns when the branch was created (first commit on branch) Falls back to first commit time if reflog is unavailable

func GetBranchNote 

func GetBranchNote(repoPath, branch string) (string, error)

GetBranchNote returns the note (description) for a branch Returns empty string if no note is set

func GetBranchWorktree 

func GetBranchWorktree(branch string) (string, error)

GetBranchWorktree returns the worktree path if branch is checked out, empty string if not

func GetCommitCount 

func GetCommitCount(repoPath, branch string) (int, error)

GetCommitCount returns number of commits ahead of the default branch

func GetCommitsBehind 

func GetCommitsBehind(repoPath, branch string) (int, error)

GetCommitsBehind returns number of commits behind the default branch

func GetCurrentBranch 

func GetCurrentBranch(path string) (string, error)

GetCurrentBranch returns the current branch name Returns "(detached)" for detached HEAD state

func GetCurrentRepoMainPath 

func GetCurrentRepoMainPath() string

GetCurrentRepoMainPath returns the main repository path from cwd Works whether you're in the main repo or a worktree Returns empty string if not in a git repo

func GetDefaultBranch 

func GetDefaultBranch(repoPath string) string

GetDefaultBranch returns the default branch name for the remote (e.g., "main" or "master")

func GetLabels 

func GetLabels(repoPath string) ([]string, error)

GetLabels returns the labels for a repository Returns empty slice if no labels are set

func GetLastCommitRelative 

func GetLastCommitRelative(path string) (string, error)

GetLastCommitRelative returns relative time of last commit

func GetLastCommitTime added in v0.2.0 

func GetLastCommitTime(path string) (time.Time, error)

GetLastCommitTime returns the unix timestamp of the last commit

func GetMainRepoPath 

func GetMainRepoPath(worktreePath string) (string, error)

GetMainRepoPath extracts main repo path from .git file in worktree

func GetMergedBranches 

func GetMergedBranches(repoPath string) map[string]bool

GetMergedBranches returns a set of branches that are merged into the default branch. Uses a single git call: `git branch --merged origin/<default>`

func GetOriginURL 

func GetOriginURL(repoPath string) (string, error)

GetOriginURL gets the origin URL for a repository

func GetRepoDisplayName added in v0.4.0 

func GetRepoDisplayName(repoPath string) string

GetRepoDisplayName returns the repo name from origin URL, falling back to folder name.

func GetRepoFolderName 

func GetRepoFolderName() (string, error)

GetRepoFolderName returns the actual folder name of the git repo on disk Uses git rev-parse --show-toplevel to get the root directory

func GetRepoName 

func GetRepoName() (string, error)

GetRepoName extracts the repository name from the origin URL

func GetRepoNameFrom 

func GetRepoNameFrom(repoPath string) (string, error)

GetRepoNameFrom extracts the repository name from the origin URL of a repo at the given path

func GetRepoNameFromWorktree added in v0.6.0 

func GetRepoNameFromWorktree(worktreePath string) string

GetRepoNameFromWorktree extracts the expected repo name from a worktree's .git file. Parses: gitdir: /path/to/repo/.git/worktrees/name Extracts: repo name from the path (parent of .git directory)

func GetShortCommitHash 

func GetShortCommitHash(path string) (string, error)

GetShortCommitHash returns the short (7 char) commit hash for HEAD in a worktree

func GetUpstreamBranch 

func GetUpstreamBranch(repoPath, branch string) string

GetUpstreamBranch returns the remote branch name for a local branch. Returns empty string if no upstream is configured.

func GroupWorktreesByRepo 

func GroupWorktreesByRepo(worktrees []Worktree) map[string][]Worktree

GroupWorktreesByRepo groups worktrees by their main repository

func HasLabel 

func HasLabel(repoPath, label string) (bool, error)

HasLabel checks if a repository has a specific label

func IsBranchMerged 

func IsBranchMerged(repoPath, branch string) (bool, error)

IsBranchMerged checks if a branch is merged into the default branch (main/master)

func IsDirty 

func IsDirty(path string) bool

IsDirty returns true if the worktree has uncommitted changes or untracked files

func IsInsideRepo 

func IsInsideRepo() bool

IsInsideRepo returns true if the current working directory is inside a git repository

func IsWorktree 

func IsWorktree(path string) bool

IsWorktree returns true if path is a git worktree (not main repo) Worktrees have .git as a file pointing to the main repo, while main repos have .git as a directory.

func IsWorktreeLinkValid added in v0.4.0 

func IsWorktreeLinkValid(worktreePath string) bool

IsWorktreeLinkValid checks if a worktree's bidirectional link is valid. Returns true if both the .git file in worktree and gitdir in main repo exist and match.

func ListPrunableWorktrees added in v0.4.0 

func ListPrunableWorktrees(repoPath string) ([]string, error)

ListPrunableWorktrees returns worktree paths that git considers stale. Uses `git worktree prune --dry-run` and parses the output.

func MoveWorktree 

func MoveWorktree(worktree Worktree, newPath string, force bool) error

MoveWorktree moves a git worktree to a new path

func ParseRepoArg 

func ParseRepoArg(repo string) (org, name string)

ParseRepoArg splits a repo argument into org and name components. "org/repo" returns ("org", "repo") "repo" returns ("", "repo")

func PruneWorktrees 

func PruneWorktrees(repoPath string) error

PruneWorktrees prunes stale worktree references

func RemoveLabel 

func RemoveLabel(repoPath, label string) error

RemoveLabel removes a label from a repository

func RemoveWorktree 

func RemoveWorktree(worktree Worktree, force bool) error

RemoveWorktree removes a git worktree

func RepairWorktree added in v0.4.0 

func RepairWorktree(repoPath, worktreePath string) error

RepairWorktree attempts to repair broken links for a single worktree. Uses `git worktree repair <path>` from the main repo.

func RepairWorktreesFromRepo added in v0.4.0 

func RepairWorktreesFromRepo(repoPath string) error

RepairWorktreesFromRepo repairs all worktrees for a repository. Uses `git worktree repair` without arguments to repair all.

func SetBranchNote 

func SetBranchNote(repoPath, branch, note string) error

SetBranchNote sets a note (description) on a branch

func SetLabels 

func SetLabels(repoPath string, labels []string) error

SetLabels sets the labels for a repository (replaces existing)

Types

type CreateWorktreeResult 

type CreateWorktreeResult struct {
	Path          string
	AlreadyExists bool
}

CreateWorktreeResult contains the result of creating a worktree

func AddWorktree 

func AddWorktree(basePath, branch, worktreeFmt string, createNew bool, baseRef string) (*CreateWorktreeResult, error)

AddWorktree creates a git worktree at basePath/<formatted-name> If createNew is true, creates a new branch (-b flag); otherwise checks out existing branch baseRef is the starting point for new branches (e.g., "origin/main")

func CreateWorktreeFrom 

func CreateWorktreeFrom(repoPath, basePath, branch, worktreeFmt, baseRef string) (*CreateWorktreeResult, error)

CreateWorktreeFrom creates a worktree from a specified repository path Used when working with a repo that isn't the current working directory baseRef is the starting point for the new branch (e.g., "origin/main", or empty for HEAD)

func OpenWorktreeFrom 

func OpenWorktreeFrom(absRepoPath, basePath, branch, worktreeFmt string) (*CreateWorktreeResult, error)

OpenWorktreeFrom creates a worktree for an existing branch in a specified repo

type DiffStats 

type DiffStats struct {
	Additions int
	Deletions int
	Files     int
}

DiffStats contains diff statistics

func GetDiffStats 

func GetDiffStats(repoPath, branch string) (DiffStats, error)

GetDiffStats returns additions, deletions, and files changed vs default branch

type Worktree 

type Worktree struct {
	Path           string    `json:"path"`
	Branch         string    `json:"branch"`
	MainRepo       string    `json:"main_repo"`
	RepoName       string    `json:"repo_name"`
	OriginURL      string    `json:"origin_url"`
	IsMerged       bool      `json:"is_merged"`
	CommitCount    int       `json:"commit_count"`
	IsDirty        bool      `json:"is_dirty"` // only populated when includeDirty=true
	HasUpstream    bool      `json:"has_upstream"`
	LastCommit     string    `json:"last_commit"`
	LastCommitTime time.Time `json:"last_commit_time"` // for sorting by commit date
	Note           string    `json:"note,omitempty"`
}

Worktree represents a git worktree with its status

func GetWorktreeInfo 

func GetWorktreeInfo(path string) (*Worktree, error)

GetWorktreeInfo returns info for a single worktree at the given path

func ListWorktrees 

func ListWorktrees(scanDir string, includeDirty bool) ([]Worktree, error)

ListWorktrees scans a directory for git worktrees with batched git calls per repo. If includeDirty is true, checks each worktree for dirty status (adds subprocess calls). For 10 worktrees across 2 repos: ~8 calls (list) or ~18 calls with dirty checks (tidy).

type WorktreeInfo 

type WorktreeInfo struct {
	Path       string
	Branch     string
	CommitHash string // Full hash from git, caller can truncate
}

WorktreeInfo contains basic worktree information from git worktree list.

func ListWorktreesFromRepo 

func ListWorktreesFromRepo(repoPath string) ([]WorktreeInfo, error)

ListWorktreesFromRepo returns all worktrees for a repository using git worktree list --porcelain. This is much faster than querying each worktree individually.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.