git

package
v0.12.7 Latest Latest
Warning

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

Go to latest
Published: Jun 19, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package git provides Git repository operations, including worktree management.

This is a Tier 1 (Leaf) package:

  • It imports ONLY stdlib and go-git packages
  • It does NOT import any internal packages
  • Directory/layout concerns are provided by caller interfaces

The package follows the Facade pattern with domain-specific sub-managers:

  • GitManager is the top-level facade owning the repository
  • WorktreeManager handles linked worktree operations

Dependency Inversion: GitManager defines WorktreeDirProvider, implemented by callers so this package stays independent of external config/layout concerns.

Package git provides Git repository operations, including worktree management. This is a Tier 1 (Leaf) package — it imports only stdlib and go-git, NOT any internal packages.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotRepository is returned when the path is not inside a git repository.
	ErrNotRepository = errors.New("not a git repository")

	// ErrBranchNotFound is returned when a branch ref does not exist.
	ErrBranchNotFound = errors.New("branch not found")

	// ErrBranchNotMerged is returned when a branch has commits not reachable from HEAD.
	ErrBranchNotMerged = errors.New("branch not fully merged")

	// ErrIsCurrentBranch is returned when attempting to delete the currently checked-out branch.
	ErrIsCurrentBranch = errors.New("cannot delete the currently checked out branch")

	// ErrBranchAlreadyExists is returned when creating a branch that already exists.
	ErrBranchAlreadyExists = errors.New("branch already exists")

	// ErrAmbiguousRemoteBranch is returned when a branch name matches remote-tracking
	// refs in more than one remote and checkout.defaultRemote does not disambiguate.
	ErrAmbiguousRemoteBranch = errors.New("branch matches multiple remotes")

	// ErrExplicitRemoteRef is returned when a worktree branch name is itself an
	// explicit remote-tracking ref (e.g. "origin/foo" where the ref exists).
	// Native git would detach HEAD there, which clawker's branch-keyed worktrees
	// do not support; the caller is steered to the bare name or colon-base form.
	ErrExplicitRemoteRef = errors.New("branch name is a remote-tracking ref")

	// ErrBranchAlreadyCheckedOut is returned when a worktree is requested for a
	// branch that is already checked out elsewhere (the repo root checkout or
	// another linked worktree). Native `git worktree add` refuses this; go-git's
	// experimental worktree package does not, so SetupWorktree enforces it.
	ErrBranchAlreadyCheckedOut = errors.New("branch is already checked out in another worktree")
)

Functions

func IsInsideWorktree

func IsInsideWorktree(path string) (bool, error)

IsInsideWorktree checks if the given path is inside a git worktree (not the main repository worktree).

Types

type GitManager

type GitManager struct {
	// contains filtered or unexported fields
}

GitManager is the top-level facade for git operations. It owns the repository handle and provides access to domain-specific sub-managers.

func NewGitManager

func NewGitManager(path string) (*GitManager, error)

NewGitManager opens the git repository containing the given path. It walks up the directory tree to find the repository root.

Returns ErrNotRepository (wrapped) if path is not inside a git repository.

func NewGitManagerWithRepo

func NewGitManagerWithRepo(repo *gogit.Repository, repoRoot string) *GitManager

NewGitManagerWithRepo creates a GitManager from an existing go-git Repository. This is primarily used for testing with in-memory repositories. The repoRoot parameter should be the logical root directory (can be a fake path for testing).

func (*GitManager) BranchExists

func (g *GitManager) BranchExists(branch string) (bool, error)

BranchExists checks if a branch exists in the repository.

func (*GitManager) CreateBranch added in v0.2.0

func (g *GitManager) CreateBranch(branch, base string) error

CreateBranch creates a new branch pointing at the given base ref. If base is empty, the branch is created from HEAD. Returns ErrBranchAlreadyExists if the branch already exists.

func (*GitManager) DeleteBranch added in v0.1.2

func (g *GitManager) DeleteBranch(branch string) error

DeleteBranch deletes a branch ref and its config (equivalent to `git branch -d`). Returns ErrIsCurrentBranch if the branch is the currently checked-out branch. Returns ErrBranchNotMerged if the branch has unmerged commits relative to HEAD. Returns ErrBranchNotFound if the branch doesn't exist.

func (*GitManager) GetCurrentBranch

func (g *GitManager) GetCurrentBranch() (string, error)

GetCurrentBranch returns the current branch name of the repository. Returns empty string and no error for detached HEAD state.

func (*GitManager) GitDir added in v0.3.0

func (g *GitManager) GitDir() string

GitDir returns the absolute path to the .git directory. Returns empty string if the storer is not filesystem-backed (e.g., in-memory repos).

func (*GitManager) IsWorktreeLocked added in v0.3.0

func (g *GitManager) IsWorktreeLocked(slug string) (bool, error)

IsWorktreeLocked checks if a worktree has a lock file (.git/worktrees/<slug>/locked). Locked worktrees are protected from pruning per git convention. Returns (locked, error). Error is non-nil for unexpected filesystem errors (permissions, etc.) — callers should not assume absence on error.

func (*GitManager) ListWorktrees

func (g *GitManager) ListWorktrees(entries []WorktreeDirEntry) ([]WorktreeInfo, error)

ListWorktrees returns information about all linked worktrees. Worktrees that have errors reading their info will have the Error field set.

Parameters:

  • entries: Worktree directory entries from the provider (name, slug, path)

The function matches entries to git worktree metadata by slug (which matches the go-git worktree name). Entries without corresponding git metadata are included with an error, as are entries that can't be opened.

func (*GitManager) RemoveWorktree

func (g *GitManager) RemoveWorktree(dirs WorktreeDirProvider, branch string) error

RemoveWorktree removes a worktree (both git metadata and directory).

Parameters:

  • dirs: Provider for worktree directory management
  • branch: Branch/worktree name to remove

func (*GitManager) RepoRoot

func (g *GitManager) RepoRoot() string

RepoRoot returns the root directory of the git repository.

func (*GitManager) Repository

func (g *GitManager) Repository() *gogit.Repository

Repository returns the underlying go-git Repository. Use this for operations not covered by the sub-managers.

func (*GitManager) ResolveRef

func (g *GitManager) ResolveRef(ref string) (plumbing.Hash, error)

ResolveRef resolves a reference (branch, tag, commit) to a commit hash.

func (*GitManager) ResolveRemoteTrackingBranch added in v0.11.0

func (g *GitManager) ResolveRemoteTrackingBranch(branch string) (remote string, hash plumbing.Hash, found bool, err error)

ResolveRemoteTrackingBranch looks for a remote-tracking ref matching branch across all configured remotes — the "dwim" rule native `git worktree add` uses when a branch name is not a local head.

It returns the remote name and tip hash when exactly one remote has refs/remotes/<remote>/<branch>. When multiple remotes match, checkout.defaultRemote disambiguates; absent that, it returns ErrAmbiguousRemoteBranch naming the candidates. When no remote has the branch, it returns found=false with a nil error so callers fall back to creating a new local branch from HEAD — exactly as native git does.

func (*GitManager) SetBranchUpstream added in v0.11.0

func (g *GitManager) SetBranchUpstream(localBranch, remote, remoteBranch string) error

SetBranchUpstream writes tracking config so localBranch tracks <remote>/<remoteBranch> (branch.<localBranch>.remote / .merge), matching `git branch --set-upstream-to`. remoteBranch is the branch name on the remote, which may differ from localBranch (e.g. `mybranch` tracking `origin/foo`).

Like git, this is an upsert: a pre-existing branch.<localBranch> config section (e.g. left behind by a plumbing-level branch deletion, or user-set keys such as branch.<name>.rebase for a branch that doesn't exist yet) is updated in place, preserving its unrelated keys, rather than rejected.

func (*GitManager) SetupWorktree

func (g *GitManager) SetupWorktree(dirs WorktreeDirProvider, branch, base string, noTrack bool) (string, error)

SetupWorktree creates or gets a worktree for the given branch. It orchestrates: directory creation (via provider) + git worktree add.

When the branch does not exist locally, SetupWorktree mirrors native `git worktree add` branch resolution:

  • base != "": create the branch at base. If base is a remote-tracking branch (e.g. "origin/foo"), the new branch is also set up to track it (git's --track default for a remote-tracking start point).
  • base == "": if a remote-tracking ref matching branch exists in exactly one remote (the "dwim" rule), branch from that remote tip and configure upstream tracking. Otherwise create a new local branch from HEAD.

Parameters:

  • dirs: Provider for worktree directory management
  • branch: Branch name to check out (created if doesn't exist)
  • base: Base ref to create branch from (empty string uses HEAD or a matching remote-tracking branch)
  • noTrack: suppress upstream tracking config even when the branch is derived from a remote-tracking ref (parity with `git worktree add --no-track`)

Returns the worktree path ready for mounting.

func (*GitManager) Worktrees

func (g *GitManager) Worktrees() (*WorktreeManager, error)

Worktrees returns the WorktreeManager for linked worktree operations. The manager is lazily initialized on first access. Returns an error if the repository's storage doesn't support worktrees.

type WorktreeDirEntry

type WorktreeDirEntry struct {
	// Name is the original name (typically a branch name with slashes).
	Name string
	// Slug is the filesystem-safe version of the name.
	Slug string
	// Path is the absolute filesystem path to the worktree directory.
	Path string
}

WorktreeDirEntry contains information about a worktree directory. This is the directory-level info (name, slug, path), separate from git metadata.

type WorktreeDirProvider

type WorktreeDirProvider interface {
	// GetOrCreateWorktreeDir returns the path to a worktree directory,
	// creating it if it doesn't exist. The name is typically a branch name;
	// the returned path is implementation-defined and filesystem-safe (no slashes).
	GetOrCreateWorktreeDir(name string) (string, error)

	// GetWorktreeDir returns the path to an existing worktree directory.
	// Returns an error if the worktree directory doesn't exist.
	GetWorktreeDir(name string) (string, error)

	// DeleteWorktreeDir removes a worktree directory.
	// Returns an error if the directory doesn't exist.
	DeleteWorktreeDir(name string) error
}

WorktreeDirProvider manages worktree directories for callers. Defined here for dependency inversion so the git package remains unconcerned with caller configuration/layout details.

type WorktreeInfo

type WorktreeInfo struct {
	// Name is the worktree name (typically the branch name).
	Name string

	// Slug is the caller-provided identifier for this worktree entry.
	// Preserved from WorktreeDirEntry to avoid re-computation.
	Slug string

	// Path is the filesystem path to the worktree directory.
	Path string

	// Head is the commit hash the worktree is checked out to.
	Head plumbing.Hash

	// Branch is the branch reference if the worktree is not detached.
	// Empty string for detached HEAD state.
	Branch string

	// IsDetached indicates whether the worktree has a detached HEAD.
	IsDetached bool

	// Error indicates any error encountered while reading worktree info.
	// If non-nil, other fields may be incomplete/zero-valued.
	Error error
}

WorktreeInfo contains information about a git worktree.

type WorktreeManager

type WorktreeManager struct {
	// contains filtered or unexported fields
}

WorktreeManager manages linked worktrees for a git repository. It wraps the experimental x/plumbing/worktree package from go-git.

func (*WorktreeManager) Add

func (w *WorktreeManager) Add(path, name string, commit plumbing.Hash) error

Add creates a linked worktree at the given path, checking out the specified commit. If commit is zero, HEAD is used.

The name parameter is used to identify the worktree in git's metadata (stored in .git/worktrees/<name>/).

func (*WorktreeManager) AddDetached

func (w *WorktreeManager) AddDetached(path, name string, commit plumbing.Hash) error

AddDetached creates a linked worktree with a detached HEAD. If commit is zero, HEAD is used.

func (*WorktreeManager) AddWithExistingBranch

func (w *WorktreeManager) AddWithExistingBranch(path, name string, branch plumbing.ReferenceName) error

AddWithExistingBranch creates a linked worktree that checks out an existing branch. Unlike AddWithNewBranch, this does NOT try to create a new branch.

Use this when the branch already exists and you want to create a worktree for it. The branch MUST exist; this method does not verify branch existence (caller's responsibility).

func (*WorktreeManager) AddWithNewBranch

func (w *WorktreeManager) AddWithNewBranch(path, name string, branch plumbing.ReferenceName, base plumbing.Hash) error

AddWithNewBranch creates a linked worktree at the given path and creates a new branch. It creates the worktree with a detached HEAD, then creates the branch pointing to base (or HEAD if base is zero), and checks out the branch.

IMPORTANT: We use AddDetached first to avoid go-git's default behavior of creating a branch named after the worktree name. This prevents the bug where slashed branch names like "feature/foo" would also create a slugified branch "feature-foo".

func (*WorktreeManager) Exists

func (w *WorktreeManager) Exists(name string) (bool, error)

Exists checks if a worktree with the given name exists in git's metadata.

func (*WorktreeManager) List

func (w *WorktreeManager) List() ([]string, error)

List returns the names of all linked worktrees.

func (*WorktreeManager) Open

func (w *WorktreeManager) Open(path string) (*gogit.Repository, error)

Open opens a linked worktree as a full *git.Repository. The path must point to an existing worktree directory.

func (*WorktreeManager) Remove

func (w *WorktreeManager) Remove(name string) error

Remove deletes the worktree metadata from .git/worktrees/. It does NOT delete the worktree directory on disk — that's the caller's responsibility.

Directories

Path Synopsis
Package gittest provides test utilities for the git package.
Package gittest provides test utilities for the git package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL