gitutil

package
v1.13.3 Latest Latest
Warning

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

 Go to latest Published: Sep 5, 2026 License: 0BSD Imports: 16 Imported by: 0

Documentation

Overview

Package gitutil wraps the system git binary. All repository access goes through git subprocesses; there is no in-process git implementation.

Index

Constants

This section is empty.

Variables

View Source 
var ErrArchiveTooLarge = errors.New("archive exceeds the size limit")
View Source 
var MaxArchiveBytes int64 = 512 << 20

Functions

func Archive 

func Archive(dir, ref, prefix string, w io.Writer) error

Archive streams a tar.gz of ref to w, within archiveTimeout and MaxArchiveBytes. Past either, git is killed and the error says which.

func AuthorIdent 

func AuthorIdent(dir, sha string) (name, email, date string, err error)

AuthorIdent returns a commit's author name, email, and ISO date.

func CommitFileChange 

func CommitFileChange(dir, branch, path string, content []byte, name, email, message string) (string, error)

CommitFileChange writes content at path on branch as a new commit and advances the branch with compare-and-swap. Used by web edits; hooks do not run, so callers enforce policy themselves.

func CommitMessage 

func CommitMessage(dir, sha string) (string, error)

CommitMessage returns a commit's full message.

func CommitParents 

func CommitParents(dir, sha string) ([]string, error)

CommitParents returns the parent SHAs of a commit.

func CommitTree 

func CommitTree(dir, tree string, parents []string, name, email, message string) (string, error)

CommitTree creates a merge commit with the given parents, authored and committed by the merging user. There is no server signing key by design.

func CommitTreeIdent 

func CommitTreeIdent(dir, tree string, parents []string,
	authorName, authorEmail, authorDate, committerName, committerEmail, message string) (string, error)

CommitTreeIdent creates a commit with distinct author and committer identities. Empty authorDate means now.

func CountCommits added in v1.0.0 

func CountCommits(dir, ref string) int

CountCommits returns the number of commits reachable from ref, or 0 when the ref does not resolve (an empty repository).

func DeleteRef 

func DeleteRef(dir, ref string) error

func Diff 

func Diff(dir, old, new string, limit int64) (patch string, truncated bool, err error)

Diff returns the patch for old..new (three-dot semantics are the caller's job: pass the merge base as old), cut at limit bytes on a line boundary; truncated says whether it was cut, so the caller can say so instead of rendering a hunk that ends mid-line (#117).

func DiffFiles added in v0.2.0 

func DiffFiles(dir, old, new string) ([]string, error)

DiffFiles lists the paths changed between old and new.

func DirSize added in v1.4.0 

func DirSize(dir string) int64

DirSize sums file sizes under dir; unreadable entries count as zero.

func FetchInto 

func FetchInto(dstDir, srcDir, srcRef, dstRef string) error

FetchInto copies srcRef from srcDir into dstDir as dstRef, forcing the update. Objects are copied, not shared — the destination owns everything afterward, which is what keeps MRs alive when their fork is deleted.

func FetchMirror 

func FetchMirror(ctx context.Context, dir, url string, errW io.Writer, extraEnv []string) error

FetchMirror pulls all branches, tags, and notes from a foreign URL into the bare repository at dir, forcing updates. Progress streams to errW so an interactive caller can watch. extraEnv carries credentials via GIT_ASKPASS; the URL itself must never contain them.

func FetchPullHeads added in v1.13.0 

func FetchPullHeads(ctx context.Context, dir, url string, errW io.Writer, extraEnv []string) error

FetchPullHeads pulls a GitHub repository's pull-request heads into refs/gh-pull/*, so an imported pull request has something to diff. GitHub publishes every PR head at refs/pull/<n>/head on the git remote, but a mirror made with the default refspecs does not carry them, which is why an import used to produce merge requests with no head at all.

One fetch for every pull request rather than one each: the ref count is the repository's history, and asking a hundred times is a hundred handshakes. extraEnv carries credentials via GIT_ASKPASS; the URL must never contain them.

func HasCommit added in v0.2.0 

func HasCommit(dir, sha string) bool

HasCommit reports whether sha names a commit object present in dir.

func InitBare 

func InitBare(path, defaultBranch, hooksPath string) error

InitBare creates a bare repository with the shared hooks directory wired via core.hooksPath.

func IsAncestor 

func IsAncestor(dir, old, new string) (bool, error)

IsAncestor reports whether old is an ancestor of new in the repository at dir. It must run with the caller's environment intact so that quarantined objects during pre-receive remain visible.

func IsBinary 

func IsBinary(data []byte) bool

IsBinary reports whether data looks like binary content.

func LFSPointerOIDs added in v1.6.0 

func LFSPointerOIDs(dir string) ([]string, error)

LFSPointerOIDs returns every LFS object id referenced by a pointer blob anywhere in the repository: every object, not just the reachable ones, since an unreachable blob is still an object gc has not removed.

func LastCommitDate added in v0.2.0 

func LastCommitDate(dir, ref string) string

LastCommitDate returns the committer date (YYYY-MM-DD) of the ref tip, or "" for empty repos.

func LastCommits added in v0.5.0 

func LastCommits(dir, ref, path string, names []string) map[string]EntryCommit

LastCommits resolves the newest commit touching each of names directly under path, for the tree at ref.

One git log process serves the whole listing rather than one per entry: the walk streams newest-first and is killed as soon as every name is accounted for, so an active directory reads only the few commits it needs no matter how deep the history goes. Names still unresolved when the walk ends are absent from the map, and callers render them blank.

func MergeBase 

func MergeBase(dir, a, b string) (string, error)

MergeBase returns the best common ancestor, or an error if none exists.

func MergeTree 

func MergeTree(dir, ours, theirs string) (tree string, conflict bool, err error)

MergeTree performs a real merge of ours and theirs, returning the merged tree id. conflict=true means the merge cannot be done automatically.

func MergeTreeOnto 

func MergeTreeOnto(dir, base, onto, commit string) (tree string, conflict bool, err error)

MergeTreeOnto replays commit's changes (relative to base) onto onto, returning the resulting tree. conflict=true when it cannot apply cleanly.

func Parents added in v0.2.0 

func Parents(dir, sha string) []string

Parents returns a commit's parent shas.

func PeelToCommit added in v0.3.0 

func PeelToCommit(dir, ref string) (string, error)

PeelToCommit resolves a ref or object to its commit — annotated tags peel to the commit they point at.

func RangeDiff added in v1.13.0 

func RangeDiff(dir, oldBase, oldHead, newBase, newHead string, limit int64) (patch string, truncated bool, err error)

RangeDiff compares two revisions of the same work: what the commits between oldBase and oldHead became between newBase and newHead. This is what answers "what changed since I reviewed this", which a plain diff of the two heads cannot — that shows the whole branch again, rebases and all.

Each side carries its own base, because the target moves: comparing both revisions against today's base would attribute every commit that landed on the target in between to the author of this merge request.

--creation-factor is raised from git's default of 60. That default is tuned for comparing two independently developed patch series, where refusing to pair is the safe answer. Here the two sides are known to be revisions of one branch, and the commonest revision of all — a commit that adds a file, with one line inside it changed — is not paired at 60: git reports the commit as deleted and a different one added, which tells a reviewer nothing. It pairs at 80, and two genuinely unrelated commits are still left unpaired there; both measured.

func ReadBlob 

func ReadBlob(dir, ref, path string, limit int64) ([]byte, error)

ReadBlob returns the contents of ref:path, capped at limit bytes.

func ReadCommit 

func ReadCommit(dir, sha string) ([]byte, error)

ReadCommit returns the raw commit object bytes.

func ReadDescription 

func ReadDescription(dir string) string

ReadDescription returns the repo's description from the classic <repo>.git/description file, empty for the git-init placeholder.

func RemoteDefaultBranch 

func RemoteDefaultBranch(ctx context.Context, url string, extraEnv []string) (string, error)

RemoteDefaultBranch asks the remote which branch HEAD points at.

func ResolveRef 

func ResolveRef(dir, ref string) (string, error)

ResolveRef resolves a ref or sha to a full commit sha; errors if absent.

func ResolveTree 

func ResolveTree(dir, sha string) (string, error)

ResolveTree returns the tree id of a commit.

func RevList 

func RevList(dir, ref string, limit int) ([]string, error)

RevList returns up to limit commit SHAs reachable from ref, newest first.

func RevListPath added in v0.3.0 

func RevListPath(dir, ref, filePath string, limit int) ([]string, error)

RevListPath returns up to limit commit SHAs reachable from ref that touch filePath, newest first. The "--" keeps the path from ever being read as an option or ref.

func RevListRange 

func RevListRange(dir, old, new string) ([]string, error)

RevListRange returns commits in old..new, newest first.

func SetHead 

func SetHead(dir, branch string) error

SetHead points the bare repo's HEAD at a branch.

func ShowPatch 

func ShowPatch(dir, sha string, limit int64) (patch string, truncated bool, err error)

ShowPatch returns the stat+patch text for one commit.

func Transport 

func Transport(service, repoPath string, stdin io.Reader, stdout, errW io.Writer, extraEnv []string, maxPack int64) error

Transport streams one git transport service (upload-pack, receive-pack, upload-archive). extraEnv entries are appended to the process environment; hooks read the GITBAY_* variables from it. maxPack caps incoming pack bytes on receive-pack (0 = unlimited).

func UpdateRefCAS 

func UpdateRefCAS(dir, ref, newSHA, oldSHA string) error

UpdateRefCAS points ref at newSHA only if it currently points at oldSHA (empty oldSHA = must not exist). This is the compare-and-swap that makes merges safe against concurrent pushes.

func WriteDescription 

func WriteDescription(dir, desc string) error

WriteDescription sets the description file: first line only, capped.

func ZeroSHA 

func ZeroSHA(s string) bool

ZeroSHA reports whether s is an all-zero object id (SHA-1 or SHA-256).

Types

type BlameHunk added in v0.2.0 

type BlameHunk struct {
	SHA         string
	AuthorName  string
	AuthorEmail string
	AuthorUnix  int64
	Summary     string
	StartLine   int // file line number of Lines[0]
	Lines       []string
}

BlameHunk is a run of consecutive lines attributed to one commit.

func Blame added in v0.2.0 

func Blame(dir, ref, path string, start, end int) ([]BlameHunk, error)

Blame attributes lines start..end (1-based, inclusive) of path at ref, merging consecutive same-commit lines into hunks.

type CommitAuthor added in v0.3.0 

type CommitAuthor struct {
	SHA   string
	Email string
	Day   string // author date, YYYY-MM-DD
}

func RevListAuthors added in v0.3.0 

func RevListAuthors(dir, old, new string, max int) ([]CommitAuthor, error)

RevListAuthors returns sha, author email, and author date for commits reachable from new but not old, capped at max. Empty or zero old lists from new alone.

type CommitMsg added in v0.2.0 

type CommitMsg struct {
	SHA         string
	Message     string
	AuthorName  string
	AuthorEmail string
}

func RevListMessages added in v0.2.0 

func RevListMessages(dir, old, new string, max int) ([]CommitMsg, error)

RevListMessages returns sha and full message for commits reachable from new but not old, newest first, capped at max. An empty or zero old (new branch) lists from new alone, still capped.

type Contributor added in v1.0.0 

type Contributor struct {
	Name    string
	Email   string
	Commits int
}

Contributor is one author of a repository's history.

func Contributors added in v1.0.0 

func Contributors(dir, ref string) []Contributor

Contributors summarises authorship reachable from ref, most commits first. Identities are keyed by email, since that is what the forge can tie back to an account, after the repository's own .mailmap has had its say — a bare repo resolves that from HEAD:.mailmap with no config.

type EntryCommit added in v0.5.0 

type EntryCommit struct {
	SHA     string
	Subject string
	Author  string
	Email   string
	When    time.Time
}

EntryCommit is the newest commit touching one entry of a tree listing.

func TipCommit added in v0.5.0 

func TipCommit(dir, ref string) EntryCommit

TipCommit is the commit at ref, for the bar above a tree listing that answers "who touched this repository last".

type GrepMatch added in v0.2.0 

type GrepMatch struct {
	Path string
	Line int
	Text string
}

func Grep added in v0.2.0 

func Grep(dir, ref, query string, max int) ([]GrepMatch, error)

Grep runs a literal, case-insensitive git grep over the tree at ref, skipping binary files. Matches are capped at max; "no matches" is an empty result, not an error.

type Language added in v1.0.0 

type Language struct {
	Name    string
	Bytes   int64
	Percent float64
}

func Languages added in v1.0.0 

func Languages(dir, ref string, lang func(path string) string) []Language

Languages reports the byte share of each language in the tree at ref, largest first, keyed by the extension map the caller supplies. Only blobs count; git's own metadata does not.

type Ref 

type Ref struct {
	Name string
	SHA  string
}

func Refs 

func Refs(dir, kind string) ([]Ref, error)

Refs lists branches or tags; kind is "heads" or "tags".

type TreeEntry 

type TreeEntry struct {
	Mode string
	Type string // blob | tree
	SHA  string
	Size int64 // -1 for trees
	Name string
}

func ListTree 

func ListTree(dir, ref, path string) ([]TreeEntry, error)

ListTree lists one level of the tree at ref:path.

func StatPath added in v0.5.0 

func StatPath(dir, ref, path string) (TreeEntry, bool)

StatPath returns the tree entry for a single path at ref, so a blob page can report the facts the file listing no longer carries: its size, and whether it is executable or a symlink.

Source Files

  • blame.go
  • facts.go
  • gitutil.go
  • grep.go
  • lastcommit.go
  • lfs.go
  • merge.go
  • messages.go
  • read.go

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.