git

package
v1.1.1 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package git provides Git operations for repository management

Index

Constants

View Source
const PullRefSpec = "+refs/pull/*/head:refs/pull/*/head"

PullRefSpec maps GitHub's pull request heads to the same names locally

Variables

View Source
var (
	ErrGitNotInstalled = errors.New("git is not installed or not in PATH")
	ErrNotAGitRepo     = errors.New("not a git repository")
	ErrCloneFailed     = errors.New("git clone failed")
	ErrPullFailed      = errors.New("git pull failed")
	ErrFetchFailed     = errors.New("git fetch failed")
	ErrSubmoduleFailed = errors.New("git submodule update failed")
)

Common errors

View Source
var (
	ErrLFSNotInstalled = errors.New("git-lfs is not installed")
	ErrLFSInstallFail  = errors.New("failed to install git-lfs")
	ErrLFSFetchFailed  = errors.New("git lfs fetch failed")
)

Common LFS errors

View Source
var (
	ErrLsRemoteFailed = errors.New("git ls-remote failed")
	ErrFsckFailed     = errors.New("git fsck failed")
	ErrLFSListFailed  = errors.New("git lfs ls-files failed")
)

Errors from the backup checks

View Source
var (
	ErrDirtyWorkTree  = errors.New("local changes, working tree not updated")
	ErrCheckoutFailed = errors.New("working tree not updated")
)

Errors from updating the working tree

View Source
var ErrSubmoduleStatusFailed = errors.New("git submodule status failed")

ErrSubmoduleStatusFailed is returned when git can't report on the submodules

Functions

This section is empty.

Types

type Commander

type Commander interface {
	// Run executes a git command and returns an error if it fails
	Run(ctx context.Context, dir string, args ...string) error

	// Output executes a git command and returns its output
	Output(ctx context.Context, dir string, args ...string) (string, error)
}

Commander provides an interface for executing git commands This interface is used for mocking in tests

type Git

type Git struct {
	// GitPath is the path to the git executable
	GitPath string
	// Quiet suppresses stdout/stderr output (for TUI mode)
	Quiet bool
	// Token is the authentication token for HTTPS operations
	Token string
	// Host is the GitHub host the token is sent to (default github.com)
	Host string
}

Git provides Git operations

func New

func New() (*Git, error)

New creates a new Git instance

func NewQuiet

func NewQuiet() (*Git, error)

NewQuiet creates a new Git instance that suppresses output

func NewQuietWithToken

func NewQuietWithToken(token string) (*Git, error)

NewQuietWithToken creates a new Git instance that suppresses output and uses auth token

func NewWithToken

func NewWithToken(token string) (*Git, error)

NewWithToken creates a new Git instance with authentication token

func (*Git) Clone

func (g *Git) Clone(ctx context.Context, url, targetDir string) error

Clone clones a repository to the target directory

func (*Git) FetchAll

func (g *Git) FetchAll(ctx context.Context, repoDir string) error

FetchAll fetches all branches from all remotes with pruning. This updates all remote-tracking branches without modifying the working directory. Use --prune to remove local references to branches deleted on remote.

func (*Git) FetchPullRefs added in v1.1.1

func (g *Git) FetchPullRefs(ctx context.Context, repoDir string) error

FetchPullRefs fetches the head commit of every pull request into refs/pull/<n>/head. These keep commits of fork and deleted branches. They are never pruned. FETCH_HEAD is left alone, since fast sync reads its time as the last full fetch.

func (*Git) Fsck added in v1.1.1

func (g *Git) Fsck(ctx context.Context, repoDir string) error

Fsck checks a repository's object store for corruption

func (*Git) GetDefaultBranch

func (g *Git) GetDefaultBranch(ctx context.Context, repoDir string) (string, error)

GetDefaultBranch returns the default branch of a repository

func (*Git) GetHEAD

func (g *Git) GetHEAD(ctx context.Context, repoDir string) (string, error)

GetHEAD returns the SHA of HEAD in the repository

func (*Git) GetLastFetchTime

func (g *Git) GetLastFetchTime(repoDir string) (time.Time, error)

GetLastFetchTime returns the modification time of .git/FETCH_HEAD, which indicates when the repository was last fetched. Returns zero time if never fetched.

func (*Git) GetRemoteBranchSHA

func (g *Git) GetRemoteBranchSHA(ctx context.Context, repoDir, remote, branch string) (string, error)

GetRemoteBranchSHA returns the SHA of a remote-tracking branch (e.g., origin/main)

func (*Git) GetRemoteURL

func (g *Git) GetRemoteURL(ctx context.Context, repoDir string) (string, error)

GetRemoteURL returns the remote origin URL for a repository

func (*Git) IsGitRepo

func (g *Git) IsGitRepo(dir string) bool

IsGitRepo checks if a directory is a git repository

func (*Git) LsRemoteDefaultBranch added in v1.1.1

func (g *Git) LsRemoteDefaultBranch(ctx context.Context, url string) (string, error)

LsRemoteDefaultBranch returns the branch the remote's HEAD points at, or "" for an empty repo

func (*Git) LsRemoteHeads added in v1.1.1

func (g *Git) LsRemoteHeads(ctx context.Context, url string) (map[string]string, error)

LsRemoteHeads returns branch name -> head SHA as the remote has them

func (*Git) LsRemotePulls added in v1.1.1

func (g *Git) LsRemotePulls(ctx context.Context, url string) (map[string]string, error)

LsRemotePulls returns pull request number -> head SHA as the remote has them

func (*Git) PullRefs added in v1.1.1

func (g *Git) PullRefs(ctx context.Context, repoDir string) (map[string]string, error)

PullRefs returns pull request number -> SHA of the local refs/pull/*/head refs

func (*Git) RemoteBranches added in v1.1.1

func (g *Git) RemoteBranches(ctx context.Context, repoDir string) (map[string]string, error)

RemoteBranches returns branch name -> SHA of the local origin/* remote-tracking refs

func (*Git) SubmoduleStatus added in v1.1.1

func (g *Git) SubmoduleStatus(ctx context.Context, repoDir string) ([]Submodule, error)

SubmoduleStatus lists every submodule, nested ones too, with its state. Repos without .gitmodules have none.

func (*Git) SubmoduleUpdate added in v1.1.1

func (g *Git) SubmoduleUpdate(ctx context.Context, repoDir string) error

SubmoduleUpdate syncs submodule URLs and checks out all submodules (recursively) of a repository. The token goes along per command, and SSH submodule URLs are fetched over HTTPS, since a backup host usually has no SSH keys. Repos without .gitmodules are a no-op.

func (*Git) UpdateWorkTree added in v1.1.1

func (g *Git) UpdateWorkTree(ctx context.Context, repoDir, branch string) (moved bool, err error)

UpdateWorkTree moves the checkout to origin/<branch>: it switches to branch if another one is checked out, then fast-forwards it. It never resets anything: with local changes it returns ErrDirtyWorkTree, and a branch that can't fast-forward returns ErrCheckoutFailed. moved is true when HEAD changed. A branch that was never fetched (an empty repo) is left alone.

type LFS

type LFS struct {
	// LFSPath is the path to the git-lfs executable
	LFSPath string
	// Git is the underlying git instance
	Git *Git
	// Quiet suppresses stdout/stderr output (inherited from Git)
	Quiet bool
}

LFS provides Git LFS operations

func NewLFS

func NewLFS(git *Git) *LFS

NewLFS creates a new LFS instance

func (*LFS) EnsureLFS

func (l *LFS) EnsureLFS(ctx context.Context) error

EnsureLFS ensures Git LFS is installed and configured

func (*LFS) Fetch

func (l *LFS) Fetch(ctx context.Context, repoDir string) error

Fetch runs 'git lfs fetch' to download LFS objects

func (*LFS) FetchAll added in v1.1.1

func (l *LFS) FetchAll(ctx context.Context, repoDir string) error

FetchAll runs 'git lfs fetch --all' to download the LFS objects of every ref, not just the checked-out one, so a backup has all of them

func (*LFS) Initialize

func (l *LFS) Initialize(ctx context.Context) error

Initialize runs 'git lfs install' to set up Git LFS hooks

func (*LFS) Install

func (l *LFS) Install(ctx context.Context) error

Install attempts to install git-lfs using the system package manager

func (*LFS) IsInstalled

func (l *LFS) IsInstalled() bool

IsInstalled checks if git-lfs is installed

func (*LFS) MissingLFSObjects added in v1.1.1

func (l *LFS) MissingLFSObjects(ctx context.Context, repoDir string) ([]string, error)

MissingLFSObjects returns the LFS objects referenced anywhere in history that are not stored locally with the right content. It needs git-lfs.

func (*LFS) Pull

func (l *LFS) Pull(ctx context.Context, repoDir string) error

Pull runs 'git lfs pull' to download LFS objects

func (*LFS) RepoUsesLFS

func (l *LFS) RepoUsesLFS(repoDir string) bool

RepoUsesLFS checks if a repository uses Git LFS

type MockCommander

type MockCommander struct {
	// RunFunc is called when Run is invoked
	RunFunc func(ctx context.Context, dir string, args ...string) error

	// OutputFunc is called when Output is invoked
	OutputFunc func(ctx context.Context, dir string, args ...string) (string, error)

	// Calls records all method calls for verification
	Calls []MockCommanderCall
}

MockCommander is a mock implementation of Commander for testing

func NewMockCommander

func NewMockCommander() *MockCommander

NewMockCommander creates a new mock commander

func (*MockCommander) CallCount

func (m *MockCommander) CallCount(method string) int

CallCount returns the number of times a method was called

func (*MockCommander) Output

func (m *MockCommander) Output(ctx context.Context, dir string, args ...string) (string, error)

Output implements Commander.Output

func (*MockCommander) Reset

func (m *MockCommander) Reset()

Reset clears all recorded calls

func (*MockCommander) Run

func (m *MockCommander) Run(ctx context.Context, dir string, args ...string) error

Run implements Commander.Run

type MockCommanderCall

type MockCommanderCall struct {
	Method string
	Dir    string
	Args   []string
}

MockCommanderCall records a method call

type Submodule added in v1.1.1

type Submodule struct {
	// Path is relative to the top repo, nested submodules included
	Path string
	// SHA is the commit the parent records for it
	SHA string
	// State is ' ' when checked out at SHA, '-' when not checked out,
	// '+' when at another commit and 'U' when it has merge conflicts
	State byte
}

Submodule is one line of git submodule status

Jump to

Keyboard shortcuts

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