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

git

package
v0.69.0 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package git provides an abstraction for git operations.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrBinaryDiff   = errors.New("binary file")
	ErrNoTextDiff   = errors.New("not a regular file")
	ErrDiffTooLarge = errors.New("diff too large")
)

FileDiff reports these instead of a diff.

View Source 
var ErrInvalidFileStatus = fmt.Errorf("not a valid FileStatus, try [%s]", strings.Join(_FileStatusNames, ", "))

Functions

func EquivalentRemote 

func EquivalentRemote(left, right string) bool

EquivalentRemote reports whether two remotes refer to the same repository under RemoteIdentity.

func ExtractHost 

func ExtractHost(remote string) string

ExtractHost extracts the host (without port) from a git remote URL. Handles SCP-style SSH (git@github.com:owner/repo.git), ssh:// and https:// URLs, and hosts with non-standard ports (git.example.com:2222). Returns an empty string when no host can be determined.

func ExtractOwnerRepo 

func ExtractOwnerRepo(remote string) (owner, repo string)

ExtractOwnerRepo extracts owner and repo from a git remote URL. Handles SSH (git@github.com:owner/repo.git) and HTTPS (https://github.com/owner/repo.git). Returns empty strings if parsing fails.

func ExtractRepoName 

func ExtractRepoName(remote string) string

ExtractRepoName extracts the repository name from a git remote URL. Handles both SSH (git@github.com:user/repo.git) and HTTPS (https://github.com/user/repo.git) formats.

func FileStatusNames added in v0.69.0 

func FileStatusNames() []string

FileStatusNames returns a list of possible string values of FileStatus.

func IsExplicitRemote added in v0.66.0 

func IsExplicitRemote(repo string) bool

IsExplicitRemote reports whether repo is already a remote or a path rather than an owner/name pair: it contains "://", "@", ":" or "\", or starts with "/", "./", "../" or "~/".

func RemoteIdentity 

func RemoteIdentity(remote string) string

RemoteIdentity returns the key under which remotes that name the same repository compare equal: host and repository path, without the transport, user, default port, or ".git" suffix. The host is lowercased everywhere but the path only on GitHub, which ignores its case; other forges may not. A local path or a remote that does not parse is returned trimmed.

func RemoteProtocol added in v0.66.0 

func RemoteProtocol(remote string) (session.CloneProtocol, bool)

RemoteProtocol returns the transport of remote: https for http(s)://, ssh for ssh:// and SCP-style [user@]host:path. ok is false for anything else, such as a local path or git://.

func ValidateBranchName 

func ValidateBranchName(s string) error

ValidateBranchName checks whether s is a valid git branch name according to git-check-ref-format(1) rules. Returns a descriptive error if invalid.

func WebURL added in v0.66.0 

func WebURL(remote string) string

WebURL returns the browser address of the repository a remote names: https://host/path, without ".git". An http(s) remote keeps its scheme and port, which are the web server's. Any other transport's port belongs to git, so WebURL drops it. A local path or a remote that does not parse returns "".

Types

type ChangedFile added in v0.69.0 

type ChangedFile struct {
	Path      string
	OldPath   string
	Status    FileStatus
	Additions int
	Deletions int
	Binary    bool
	Stamp     string
}

ChangedFile is one path that differs from a diff's base. OldPath is set for a rename. Untracked files carry no line counts, so a list's totals match DiffStats and a poll reads no file contents.

Stamp changes when the file's diff across this range can. Line counts alone can't tell a reader that its diff is stale: replacing one line with another leaves them the same, and an untracked file has none.

type CommitInfo added in v0.69.0 

type CommitInfo struct {
	ID      string
	Subject string
	Author  string
	Unix    int64
}

CommitInfo is one commit Commits lists.

type DiffRange added in v0.69.0 

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

DiffRange is the two sides of a diff. Build one with WorkingTree, Staged, Unstaged or Commit.

func Staged added in v0.69.0 

func Staged() DiffRange

Staged compares the index with HEAD.

func Unstaged added in v0.69.0 

func Unstaged() DiffRange

Unstaged compares the working tree with the index. It lists untracked files.

func WorkingTree added in v0.69.0 

func WorkingTree(ref string) DiffRange

WorkingTree compares the working tree with ref. It lists untracked files.

type Executor 

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

Executor implements Git using the git command-line tool.

func NewExecutor 

func NewExecutor(gitPath string, exec executil.Executor) *Executor

NewExecutor creates a new git executor with the specified git binary path.

func (*Executor) Branch 

func (e *Executor) Branch(ctx context.Context, dir string) (string, error)

func (*Executor) Branches added in v0.69.0 

func (e *Executor) Branches(ctx context.Context, dir string, limit int) ([]string, error)

Branches lists the full refs of local and remote branches, most recently committed first. A symbolic ref such as origin/HEAD only repeats a branch.

func (*Executor) ChangedFiles added in v0.69.0 

func (e *Executor) ChangedFiles(ctx context.Context, dir string, diff DiffRange) ([]ChangedFile, error)

ChangedFiles lists what differs across diff, sorted by path, plus untracked files when diff includes the working tree.

func (*Executor) Checkout 

func (e *Executor) Checkout(ctx context.Context, dir, branch string) error

func (*Executor) Clone 

func (e *Executor) Clone(ctx context.Context, url, dest string) error

func (*Executor) CloneBare 

func (e *Executor) CloneBare(ctx context.Context, url, dest string) error

func (*Executor) CommitRange added in v0.69.0 

func (e *Executor) CommitRange(ctx context.Context, dir, commit string) (DiffRange, error)

CommitRange compares a commit with its first parent, or with the empty tree for a root commit. It takes the id ResolveCommit returned.

func (*Executor) Commits added in v0.69.0 

func (e *Executor) Commits(ctx context.Context, dir, since string, limit int) ([]CommitInfo, error)

Commits lists the commits reachable from HEAD and not from since, newest first. An empty since lists HEAD's history.

func (*Executor) DefaultBranch 

func (e *Executor) DefaultBranch(ctx context.Context, dir string) (string, error)

func (*Executor) DiffStats 

func (e *Executor) DiffStats(ctx context.Context, dir string) (additions, deletions int, err error)

func (*Executor) Fetch 

func (e *Executor) Fetch(ctx context.Context, dir string) error

func (*Executor) FileDiff added in v0.69.0 

func (e *Executor) FileDiff(ctx context.Context, dir string, diff DiffRange, file ChangedFile) (string, error)

FileDiff returns the unified diff of one file across diff, or ErrBinaryDiff, ErrNoTextDiff or ErrDiffTooLarge. An untracked file that has vanished returns an error matching fs.ErrNotExist.

func (*Executor) FileDiffs added in v0.69.0 

func (e *Executor) FileDiffs(ctx context.Context, dir string, diff DiffRange, files []ChangedFile) []FileDiffResult

FileDiffs returns the diff of each file, in order. One git diff covers the tracked files, because a process and an index copy for each file costs far more than the diff itself. A file that run cannot answer is read on its own: a path git quotes, a file no longer changed, or every file when the run fails or passes maxBatchDiffBytes. So a failure stays with the one file it belongs to.

func (*Executor) HasUnpushedCommits 

func (e *Executor) HasUnpushedCommits(ctx context.Context, dir string) (bool, error)

func (*Executor) IsClean 

func (e *Executor) IsClean(ctx context.Context, dir string) (bool, error)

func (*Executor) IsValidRepo 

func (e *Executor) IsValidRepo(ctx context.Context, dir string) error

func (*Executor) MergeBase added in v0.69.0 

func (e *Executor) MergeBase(ctx context.Context, dir, branch string) (string, error)

MergeBase returns the commit where HEAD left branch. It prefers origin/<branch>, because a checkout's local default branch goes stale and would inflate the diff. A bare clone's worktree has no remote refs, so there it uses the local branch.

func (*Executor) MergeBaseRef added in v0.69.0 

func (e *Executor) MergeBaseRef(ctx context.Context, dir, ref string) (string, error)

MergeBaseRef returns the commit where HEAD left a full ref, exactly as named.

func (*Executor) Pull 

func (e *Executor) Pull(ctx context.Context, dir string) error

func (*Executor) RemoteURL 

func (e *Executor) RemoteURL(ctx context.Context, dir string) (string, error)

func (*Executor) ResetHard 

func (e *Executor) ResetHard(ctx context.Context, dir string) error

func (*Executor) ResolveCommit added in v0.69.0 

func (e *Executor) ResolveCommit(ctx context.Context, dir, rev string) (string, error)

ResolveCommit returns the full id of rev, or fails when it names no commit.

func (*Executor) SetRemoteURL added in v0.66.0 

func (e *Executor) SetRemoteURL(ctx context.Context, dir, url string) error

func (*Executor) WorktreeAdd 

func (e *Executor) WorktreeAdd(ctx context.Context, repoDir, path, branch string) error

func (*Executor) WorktreeRemove 

func (e *Executor) WorktreeRemove(ctx context.Context, repoDir, path, branch string) error

type FileDiffResult added in v0.69.0 

type FileDiffResult struct {
	Text string
	Err  error
}

FileDiffResult is the outcome of one file in FileDiffs. Err holds what FileDiff would return.

type FileStatus added in v0.69.0 

type FileStatus string

ENUM(modified, added, deleted, renamed, untracked) 

const (
	// FileStatusModified is a FileStatus of type modified.
	FileStatusModified FileStatus = "modified"
	// FileStatusAdded is a FileStatus of type added.
	FileStatusAdded FileStatus = "added"
	// FileStatusDeleted is a FileStatus of type deleted.
	FileStatusDeleted FileStatus = "deleted"
	// FileStatusRenamed is a FileStatus of type renamed.
	FileStatusRenamed FileStatus = "renamed"
	// FileStatusUntracked is a FileStatus of type untracked.
	FileStatusUntracked FileStatus = "untracked"
)

func ParseFileStatus added in v0.69.0 

func ParseFileStatus(name string) (FileStatus, error)

ParseFileStatus attempts to convert a string to a FileStatus.

func (*FileStatus) AppendText added in v0.69.0 

func (x *FileStatus) AppendText(b []byte) ([]byte, error)

AppendText appends the textual representation of itself to the end of b (allocating a larger slice if necessary) and returns the updated slice.

Implementations must not retain b, nor mutate any bytes within b[:len(b)].

func (FileStatus) IsValid added in v0.69.0 

func (x FileStatus) IsValid() bool

IsValid provides a quick way to determine if the typed value is part of the allowed enumerated values

func (FileStatus) MarshalText added in v0.69.0 

func (x FileStatus) MarshalText() ([]byte, error)

MarshalText implements the text marshaller method.

func (FileStatus) String added in v0.69.0 

func (x FileStatus) String() string

String implements the Stringer interface.

func (*FileStatus) UnmarshalText added in v0.69.0 

func (x *FileStatus) UnmarshalText(text []byte) error

UnmarshalText implements the text unmarshaller method.

type Git 

type Git interface {
	// Clone clones a repository from url to dest.
	Clone(ctx context.Context, url, dest string) error
	// Checkout switches to the specified branch in dir.
	Checkout(ctx context.Context, dir, branch string) error
	// Pull fetches and merges changes in dir.
	Pull(ctx context.Context, dir string) error
	// ResetHard discards all local changes in dir.
	ResetHard(ctx context.Context, dir string) error
	// RemoteURL returns the origin remote URL for dir.
	RemoteURL(ctx context.Context, dir string) (string, error)
	// SetRemoteURL points origin in dir at url.
	SetRemoteURL(ctx context.Context, dir, url string) error
	// IsClean returns true if there are no uncommitted changes in dir.
	IsClean(ctx context.Context, dir string) (bool, error)
	// Branch returns the current branch name, or short commit SHA if in detached HEAD state.
	Branch(ctx context.Context, dir string) (string, error)
	// DefaultBranch returns the default branch name (e.g., "main" or "master") for the repository.
	DefaultBranch(ctx context.Context, dir string) (string, error)
	// DiffStats returns the lines added and deleted in the working tree against
	// the merge base with the default branch, or against HEAD without one.
	DiffStats(ctx context.Context, dir string) (additions, deletions int, err error)
	// IsValidRepo checks if dir contains a valid git repository.
	IsValidRepo(ctx context.Context, dir string) error
	// CloneBare creates a bare clone of url at dest.
	CloneBare(ctx context.Context, url, dest string) error
	// WorktreeAdd creates a new worktree at path on a new branch named branch.
	WorktreeAdd(ctx context.Context, repoDir, path, branch string) error
	// WorktreeRemove removes the worktree at path and deletes branch from repoDir when provided.
	WorktreeRemove(ctx context.Context, repoDir, path, branch string) error
	// Fetch fetches all remotes in dir.
	Fetch(ctx context.Context, dir string) error
	// HasUnpushedCommits returns true if there are local commits not yet pushed to a remote.
	// It first checks the upstream tracking branch; if none is set, it falls back to comparing
	// against origin/<default branch>. Returns false (no risk) on any git error.
	HasUnpushedCommits(ctx context.Context, dir string) (bool, error)
	// MergeBase returns the commit where HEAD left branch.
	MergeBase(ctx context.Context, dir, branch string) (string, error)
	// MergeBaseRef returns the commit where HEAD left a full ref.
	MergeBaseRef(ctx context.Context, dir, ref string) (string, error)
	// ResolveCommit returns the full id of rev.
	ResolveCommit(ctx context.Context, dir, rev string) (string, error)
	// CommitRange returns the range that shows one commit.
	CommitRange(ctx context.Context, dir, commit string) (DiffRange, error)
	// Commits lists the commits on HEAD after since, newest first.
	Commits(ctx context.Context, dir, since string, limit int) ([]CommitInfo, error)
	// Branches lists the full refs of local and remote branches.
	Branches(ctx context.Context, dir string, limit int) ([]string, error)
	// ChangedFiles lists what differs across diff, plus untracked files when diff includes the working tree.
	ChangedFiles(ctx context.Context, dir string, diff DiffRange) ([]ChangedFile, error)
	// FileDiffs returns the unified diff of each file, in order.
	FileDiffs(ctx context.Context, dir string, diff DiffRange, files []ChangedFile) []FileDiffResult
}

Git defines git operations needed by hive.

type RepoLocation added in v0.66.0 

type RepoLocation struct {
	// Host is the hostname plus a non-default port. Only HTTPS URLs use the port.
	Host string
	// Path is owner/name or group/subgroup/name, without ".git".
	Path string
}

RepoLocation is a forge host and repository path a clone URL can be built for.

func ItemRepoLocation added in v0.66.0 

func ItemRepoLocation(repo, itemURL string) (RepoLocation, bool)

ItemRepoLocation expands an item's owner/repo using the host of its http(s) web URL. ok is false for an explicit remote, a malformed repo, or a URL without a host.

func (RepoLocation) Candidates added in v0.66.0 

func (l RepoLocation) Candidates() []string

Candidates returns the HTTPS and SSH URLs, so a rule pattern written for either transport matches.

func (RepoLocation) CloneURL added in v0.66.0 

func (l RepoLocation) CloneURL(p session.CloneProtocol) string

CloneURL renders https://host[:port]/path.git, or git@hostname:path.git for SSH. SSH never carries a port: a forge whose SSH port differs from its web port needs an explicit repo_template.

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.