Help us shape the future of Go! Take the 2026 Go Developer Survey

git

package
v1.7.0 Latest Latest
Warning

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

 Go to latest Published: Oct 21, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package git provides the Runner interface and its system-git implementation.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrRebaseConflict means the rebase stopped on a conflict and is still in
	// progress; the caller should run RebaseAbort.
	ErrRebaseConflict = errors.New("rebase conflict")
	// ErrAutostashConflict means the rebase completed but re-applying the
	// autostash conflicted; the changes are kept in the stash.
	ErrAutostashConflict = errors.New("autostash could not be re-applied cleanly")
	// ErrUntrackedBlocked means untracked files would be overwritten by the new
	// base; git refused to rebase and the worktree is unchanged.
	ErrUntrackedBlocked = errors.New("untracked files would be overwritten")
)

Sentinel errors returned (wrapped) by Rebase so callers can tell the recoverable failure modes apart from other errors; see docs/adr/0018-workspace-rebase.md (D2, D6).

View Source 
var ErrRepairUnsupported = errors.New("git worktree repair requires git ≥ 2.29")

ErrRepairUnsupported is returned by WorktreeRepair when the installed git version predates 2.29 and does not support the repair subcommand.

Functions

This section is empty.

Types

type FileStatus 

type FileStatus struct {
	Path     string
	Index    byte // X: staged change ('.' = clean, 'M' = modified, 'A' = added, etc.)
	Worktree byte // Y: unstaged change
}

FileStatus holds the porcelain v2 XY status codes for a single file.

type RepoStatus 

type RepoStatus struct {
	Branch   string
	Upstream string // empty if no upstream is configured
	Ahead    int
	Behind   int
	Files    []FileStatus
}

RepoStatus summarises the working-tree and branch state of a repository.

type Runner 

type Runner interface {
	// Worktrees
	WorktreeAdd(repoPath, worktreePath, branch, base string, createBranch bool) error
	WorktreeRemove(repoPath, worktreePath string, force bool) error
	WorktreeList(repoPath string) ([]WorktreeInfo, error)
	WorktreeRepair(repoPath string, paths ...string) error // ErrRepairUnsupported on git < 2.29

	// Branches
	BranchExists(repoPath, branch string) (bool, error)
	RemoteBranchExists(repoPath, branch string) (bool, error)
	BranchDelete(repoPath, branch string, force bool) error
	BranchMerged(repoPath, branch string) (bool, error) // is branch merged into HEAD?

	// Status
	Status(repoPath string) (RepoStatus, error) // git status --porcelain=v2 --branch

	// Pending work
	// PendingWork returns the number of commits on any local branch that exist
	// on no remote, plus the number of stash entries. Both travel with a repo
	// that is moved rather than deleted, so callers treat them as advisory
	// warnings (see docs/adr/0013-repo-archive.md).
	PendingWork(repoPath string) (unpushedCommits, stashes int, err error)

	// Sync
	DefaultBranch(repoPath string) (string, error)
	Fetch(repoPath string) error
	FastForward(repoPath, branch string) error
	Push(repoPath, branch string) error
	// Rebase runs "git rebase --autostash <onto>". Failures are wrapped with
	// ErrRebaseConflict, ErrAutostashConflict or ErrUntrackedBlocked when
	// they match; use errors.Is.
	Rebase(repoPath, onto string) error
	RebaseAbort(repoPath string) error
	// IsAncestor reports whether ancestor is an ancestor of (or equal to) descendant.
	IsAncestor(repoPath, ancestor, descendant string) (bool, error)
	// InProgress returns the multi-step operation under way in the worktree
	// ("rebase", "merge", "cherry-pick" or "revert"), or "" if there is none.
	InProgress(repoPath string) (string, error)
	// ShortRev resolves rev to an abbreviated commit hash.
	ShortRev(repoPath, rev string) (string, error)

	// Info
	RemoteURL(repoPath, remote string) (string, error)
	Remotes(repoPath string) ([]string, error) // list configured remote names
}

Runner is the interface through which all git operations are performed. The production implementation shells out to system git; tests use a mock or a real git repo created with internal/git/testhelper.

type SystemRunner 

type SystemRunner struct{}

SystemRunner is the production Runner implementation that shells out to system git.

func New 

func New() *SystemRunner

New returns a SystemRunner.

func (*SystemRunner) BranchDelete 

func (r *SystemRunner) BranchDelete(repoPath, branch string, force bool) error

func (*SystemRunner) BranchExists 

func (r *SystemRunner) BranchExists(repoPath, branch string) (bool, error)

func (*SystemRunner) BranchMerged 

func (r *SystemRunner) BranchMerged(repoPath, branch string) (bool, error)

func (*SystemRunner) DefaultBranch 

func (r *SystemRunner) DefaultBranch(repoPath string) (string, error)

DefaultBranch returns the default branch of the "origin" remote, e.g. "main".

It reads the cached origin/HEAD symbolic ref, which git populates on clone. That ref is absent in some repos (e.g. those not created by "git clone") and can also be a plain commit ref rather than a symbolic one, in which case "git symbolic-ref" fails with "is not a symbolic ref". When the cached ref cannot be read, DefaultBranch asks the remote via "git remote set-head origin --auto" — which discovers and repairs origin/HEAD — and reads it again.

That repair fails when origin's default branch has never been fetched, since git refuses to point origin/HEAD at a remote-tracking ref that does not exist locally ("Not a valid ref: refs/remotes/origin/<branch>"). DefaultBranch then falls back to asking the remote directly with "git ls-remote --symref origin HEAD", which does not depend on any local ref.

func (*SystemRunner) FastForward 

func (r *SystemRunner) FastForward(repoPath, branch string) error

func (*SystemRunner) Fetch 

func (r *SystemRunner) Fetch(repoPath string) error

func (*SystemRunner) InProgress added in v1.7.0 

func (r *SystemRunner) InProgress(repoPath string) (string, error)

func (*SystemRunner) IsAncestor added in v1.7.0 

func (r *SystemRunner) IsAncestor(repoPath, ancestor, descendant string) (bool, error)

func (*SystemRunner) PendingWork added in v1.6.0 

func (r *SystemRunner) PendingWork(repoPath string) (int, int, error)

func (*SystemRunner) Push 

func (r *SystemRunner) Push(repoPath, branch string) error

func (*SystemRunner) Rebase 

func (r *SystemRunner) Rebase(repoPath, onto string) error

Rebase runs "git rebase --autostash onto". It classifies failures instead of trusting git's exit status alone:

  • a rebase still in progress afterwards means a conflict (ErrRebaseConflict);
  • a stash entry that was not there before means the autostash could not be re-applied (ErrAutostashConflict), whatever the exit status was;
  • git's "untracked working tree files would be overwritten" refusal means ErrUntrackedBlocked.

func (*SystemRunner) RebaseAbort added in v1.7.0 

func (r *SystemRunner) RebaseAbort(repoPath string) error

func (*SystemRunner) RemoteBranchExists 

func (r *SystemRunner) RemoteBranchExists(repoPath, branch string) (bool, error)

func (*SystemRunner) RemoteURL 

func (r *SystemRunner) RemoteURL(repoPath, remote string) (string, error)

func (*SystemRunner) Remotes 

func (r *SystemRunner) Remotes(repoPath string) ([]string, error)

func (*SystemRunner) ShortRev added in v1.7.0 

func (r *SystemRunner) ShortRev(repoPath, rev string) (string, error)

func (*SystemRunner) Status 

func (r *SystemRunner) Status(repoPath string) (RepoStatus, error)

func (*SystemRunner) WorktreeAdd 

func (r *SystemRunner) WorktreeAdd(repoPath, worktreePath, branch, base string, createBranch bool) error

func (*SystemRunner) WorktreeList 

func (r *SystemRunner) WorktreeList(repoPath string) ([]WorktreeInfo, error)

func (*SystemRunner) WorktreeRemove 

func (r *SystemRunner) WorktreeRemove(repoPath, worktreePath string, force bool) error

func (*SystemRunner) WorktreeRepair 

func (r *SystemRunner) WorktreeRepair(repoPath string, paths ...string) error

type WorktreeInfo 

type WorktreeInfo struct {
	Path   string
	HEAD   string // commit hash
	Branch string // empty if HEAD is detached
	Bare   bool
	Locked bool
}

WorktreeInfo describes a single git worktree.

Source Files

View all Source files

Directories

Path Synopsis
Package testhelper creates real git repositories in t.TempDir() for use in integration tests of the git.Runner implementation.
 Package testhelper creates real git repositories in t.TempDir() for use in integration tests of the git.Runner implementation.

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.