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

git

package
v0.1.6 Latest Latest
Warning

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

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

Documentation

Overview

Package git reads a checkout's uncommitted changes from git's own files: HEAD, refs, objects, and the index. It never runs git and knows no HTTP or document policy.

Changes compare HEAD with the working tree. Clean and smudge filters are not applied, submodules and nested repositories are skipped, and renames are exact content matches only.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotRepository is returned when a directory has no .git entry naming
	// a git directory.
	ErrNotRepository = errors.New("not a git repository")
	// ErrUnchanged is returned for a tracked path identical to HEAD.
	ErrUnchanged = errors.New("no changes since HEAD")
	// ErrUnavailable is returned for a path that is not a change.
	ErrUnavailable = errors.New("not a change")
)
View Source
var (
	// ErrRangeTooLarge is returned when a branch range exceeds branchLimit or
	// its walk exceeds walkLimit.
	ErrRangeTooLarge = errors.New("too many commits to compare")
	// ErrUnknownBase is returned for a base branch name Branches does not
	// list.
	ErrUnknownBase = errors.New("unknown base branch")
	// ErrUnknownHead is returned for a head branch name that is not a local
	// branch Branches lists.
	ErrUnknownHead = errors.New("unknown head branch")
)

Functions

func BlobHash

func BlobHash(content []byte) string

BlobHash returns the git blob hash content would be stored under.

func LineChanges

func LineChanges(old, new []byte) (added, deleted int)

LineChanges counts the lines a line diff from old to new adds and removes, as git diff --numstat does. A line ends after "\n"; a last line without one differs from the same text with one.

Types

type Author

type Author struct {
	Name  string `json:"name"`
	Email string `json:"email"`
}

Author is who wrote a commit.

type Blob

type Blob struct {
	Size int64
	// contains filtered or unexported fields
}

Blob is a HEAD file's content, sized before it is read.

func (Blob) Hash

func (b Blob) Hash() string

Hash returns the blob's 40-hexadecimal-digit git hash.

func (Blob) Open

func (b Blob) Open() (io.ReadCloser, error)

Open returns the blob's content.

type BranchList

type BranchList struct {
	Branches []BranchRef
	// Truncated reports that the limit dropped branches.
	Truncated bool
}

BranchList is a repository's branches: local ones, then remote-tracking ones, each sorted by name in byte order.

type BranchRange

type BranchRange struct {
	// Base is the base branch's short name, or empty when none was given and
	// none exists.
	Base string
	// MergeBase is the best common ancestor of the base and Head; zero when
	// nothing is ahead or the histories are unrelated.
	MergeBase Hash
	// Head is the head's commit: HEAD's, or the named head branch's tip;
	// zero when HEAD is unborn.
	Head Hash
	// Ahead counts the commits in base..Head, as Log does.
	Ahead int
}

BranchRange is a head's branch range against the base branch.

type BranchRef

type BranchRef struct {
	Name   string `json:"name"`
	Remote bool   `json:"remote"`
}

BranchRef is a branch a compare may use as its base. Name is git's short form: "main" for a local branch, "origin/main" for a remote-tracking one.

type Change

type Change struct {
	Path    string `json:"path"`
	OldPath string `json:"oldPath,omitempty"`
	Status  Status `json:"status"`
}

Change is one changed path. Paths are slash-separated and relative to the worktree root; OldPath is set for renames only.

type Changes

type Changes struct {
	Files []Change
	// Truncated reports that Limit dropped changes.
	Truncated bool
	// Warnings are directories the untracked walk could not read.
	Warnings []files.Warning
}

Changes is a worktree's changes since HEAD, sorted by path in byte order.

type Commit

type Commit struct {
	Hash    string
	Parents []string
	// Subject is the message's first line; Body is the rest without leading
	// blank lines or trailing whitespace.
	Subject    string
	Body       string
	Author     Author
	AuthorTime time.Time
}

Commit is one commit's summary. Shallow commits have no parents.

type CommitChanges

type CommitChanges struct {
	Files []Change
	// Truncated reports that the limit dropped changes.
	Truncated bool
}

CommitChanges are a commit's changes against its first parent, sorted by path in byte order.

type Entry

type Entry struct {
	Change
	// Symlink reports that the worktree side is a symbolic link; Link is its
	// target text, which is the content git records.
	Symlink bool
	Link    string
}

Entry is a validated change and what reading its worktree side needs.

type Hash

type Hash plumbing.Hash

Hash is a full commit hash; the zero Hash is unset. It keeps go-git types inside this package.

func ParseHash

func ParseHash(value string) (Hash, bool)

ParseHash parses a full commit hash: 40 lowercase hexadecimal digits.

func (Hash) IsZero

func (h Hash) IsZero() bool

IsZero reports whether h is unset.

func (Hash) String

func (h Hash) String() string

String returns the 40 hexadecimal digits.

type History

type History struct {
	// Head is the commit walked; zero when HEAD is unborn.
	Head Hash
	// Base is the base branch's short name, or empty when none exists.
	Base string
	// Ahead counts the commits in base..Head; zero without a base.
	Ahead   int
	Commits []Commit
	// More reports that commits follow this page.
	More bool
}

History is one page of commits, newest committer date first.

type LogOptions

type LogOptions struct {
	Range Range
	// Head is the commit to walk from; zero resolves HEAD. Pinning it keeps
	// pages stable while new commits arrive.
	Head Hash
	// Skip and Limit page the commits; a Limit of zero or less returns all.
	Skip, Limit int
	// Base names the base branch as Branches lists it; empty finds it as
	// DefaultBase does.
	Base string
}

LogOptions select and page a history read.

type Range

type Range string

Range selects which commits Log lists.

const (
	// RangeBranch lists commits reachable from the head and not from the
	// base branch, as git log base..head does.
	RangeBranch Range = "branch"
	// RangeAll lists the head's whole history.
	RangeAll Range = "all"
)

type Repository

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

Repository is an open worktree. Close releases its files.

func Open

func Open(dir string) (*Repository, error)

Open opens the worktree whose root is the absolute, symlink-evaluated directory dir, following a linked worktree's .git file and commondir to the shared git directory.

func (*Repository) Branch

func (r *Repository) Branch() string

Branch is the checked-out branch, or empty when HEAD is detached or unreadable.

func (*Repository) BranchCompare

func (r *Repository) BranchCompare(ctx context.Context, base, head string) (BranchRange, error)

BranchCompare finds a head's branch range and merge base within the bounds of Log's branch walk. With several best common ancestors, as after criss-cross merges, the newest committer date wins. base names the base branch as Branches lists it, or is empty for DefaultBase's. head names a local branch to compare, or is empty for HEAD. It returns ErrUnknownBase for an unlisted base, ErrUnknownHead for a head that is not a local branch, and ErrRangeTooLarge past the bounds.

func (*Repository) BranchFiles

func (r *Repository) BranchFiles(ctx context.Context, base, head string, limit int) (BranchRange, CommitChanges, error)

BranchFiles compares the merge base's tree with Head's, as git diff base...head does; unrelated histories compare with an empty tree. Nothing ahead lists no changes. Statuses, renames, and the limit follow CommitFiles; base and head follow BranchCompare.

func (*Repository) BranchLookup

func (r *Repository) BranchLookup(ctx context.Context, base, head, name, oldPath string) (BranchRange, Change, error)

BranchLookup validates one change of the branch under BranchFiles's rules, as CommitLookup does for a commit. Sides read through CommitBlob at MergeBase and Head. base and head follow BranchCompare; an unknown base or head is ErrUnknownBase or ErrUnknownHead whatever the path.

func (*Repository) Branches

func (r *Repository) Branches(limit int) (BranchList, error)

Branches lists the local and remote-tracking branches, leaving out symbolic refs such as origin/HEAD. A limit of zero or less lists all.

func (*Repository) Close

func (r *Repository) Close() error

Close releases the repository's open files.

func (*Repository) CommitBlob

func (r *Repository) CommitBlob(hash Hash, name string) (Blob, error)

CommitBlob returns the file name has in a commit. It returns ErrUnavailable when the commit is unknown or has no file there.

func (*Repository) CommitFiles

func (r *Repository) CommitFiles(ctx context.Context, hash Hash, limit int) (CommitChanges, error)

CommitFiles compares a commit's tree with its first parent's, or with an empty tree for a root commit. Statuses are modified, added, deleted, and renamed; a deleted and an added file of identical content and mode pair as a rename, both in path order. Submodules are skipped. A limit of zero or less returns all changes. It returns ErrUnavailable for an unknown commit.

func (*Repository) CommitLookup

func (r *Repository) CommitLookup(ctx context.Context, hash Hash, name, oldPath string) (Change, error)

CommitLookup validates one change of a commit under CommitFiles's rules. Without oldPath, a path a rename created reports the rename. A deleted path a rename consumed, or anything else that is not a change, is ErrUnavailable.

func (*Repository) DefaultBase

func (r *Repository) DefaultBase() (string, error)

DefaultBase finds the base branch: origin's HEAD target, then main, master, origin/main, and origin/master. It returns an empty name when none resolves.

func (*Repository) Entries

func (r *Repository) Entries(changes []Change) ([]Entry, error)

Entries completes changes Status listed with what reading their worktree sides needs: whether each path is now a symbolic link, and its target text. Deleted changes have no worktree side and are returned as they are.

func (*Repository) HeadBlob

func (r *Repository) HeadBlob(name string) (Blob, error)

HeadBlob returns the file name has in HEAD. It returns ErrUnavailable when HEAD has no file there.

func (*Repository) Log

func (r *Repository) Log(ctx context.Context, options LogOptions) (History, error)

Log lists one page of history from options.Head. Commits are ordered like git log: newest committer date first, from a priority queue, so a parent can precede a child only under clock skew. It returns ErrUnavailable when a given Head is not a commit, and ErrRangeTooLarge when the base..Head range exceeds its bounds. RangeAll still lists a page then, with Ahead zero. An options.Base Branches does not list is ErrUnknownBase.

func (*Repository) Lookup

func (r *Repository) Lookup(ctx context.Context, name, oldPath string) (Entry, error)

Lookup classifies one path without walking the worktree. With oldPath it validates a rename: oldPath is in HEAD and gone from the worktree, and path is a new file with oldPath's content. It returns ErrUnchanged for a tracked path identical to HEAD and ErrUnavailable for anything else that is not a change.

func (*Repository) ParentBlob

func (r *Repository) ParentBlob(hash Hash, name string) (Blob, error)

ParentBlob returns the file name has in a commit's first parent. It returns ErrUnavailable when the commit is unknown, has no parent, or the parent has no file there.

func (*Repository) RangeFiles

func (r *Repository) RangeFiles(ctx context.Context, from, to Hash, limit int) (CommitChanges, error)

RangeFiles compares the first parent of from, the oldest commit of a range, with to, its newest, as git diff from^ to does: only the two trees count. A root or shallow from compares with an empty tree. Statuses, renames, and the limit follow CommitFiles. It returns ErrUnavailable for an unknown commit.

func (*Repository) RangeLookup

func (r *Repository) RangeLookup(ctx context.Context, from, to Hash, name, oldPath string) (Change, error)

RangeLookup validates one change of a range under RangeFiles's rules, as CommitLookup does for a commit.

func (*Repository) Stack

func (r *Repository) Stack(ctx context.Context, base string) (Stack, error)

Stack finds the local branches stacked with HEAD on the base branch. A branch is a layer when its tip is in base..HEAD (below HEAD) or HEAD is in base..tip (above HEAD); tips reachable from the base are not. HEAD's own layer is always listed. Branches at one tip share a layer: HEAD's, else the first by name. A layer's parent is the layer below it with the largest range, or the base. Without a base, with an unborn HEAD, or with nothing ahead, there are no layers. Every walk shares Log's bounds; past them, or past stackCandidateLimit branches, the rest are skipped and Truncated is set. base follows BranchCompare.

func (*Repository) Status

func (r *Repository) Status(ctx context.Context, options StatusOptions) (Changes, error)

Status compares HEAD, the index, and the working tree. Tracked paths are reported even when ignore rules match them; untracked files are found by walking the worktree without ignored directories. A deleted path and an added or untracked path with the same content pair as a rename.

type Stack

type Stack struct {
	// Base is the base branch's short name, or empty when none was given and
	// none exists.
	Base string
	// MergeBase and Head follow BranchCompare.
	MergeBase Hash
	Head      Hash
	// Branch is HEAD's branch; empty when detached.
	Branch string
	// Layers run from the farthest from the base to the nearest.
	Layers []StackLayer
	// Truncated reports that the candidate limit or the walk bounds left
	// branches unconsidered.
	Truncated bool
}

Stack is HEAD's branch stack against the base branch.

type StackLayer

type StackLayer struct {
	// Name is the branch's short name; empty for a detached HEAD.
	Name string
	// Aliases are the other local branches at the same tip, sorted.
	Aliases []string
	// Head is the layer's tip.
	Head Hash
	// Parent names the nearest layer below, or the base branch.
	Parent string
	// Ahead counts the commits in the layer's range and not its parent's.
	Ahead int
	// Current marks HEAD's layer.
	Current bool
}

StackLayer is one branch of a stack: a local branch whose base..tip range holds HEAD or lies within HEAD's, or HEAD itself.

type Status

type Status string

Status describes how a path differs from HEAD.

const (
	Modified  Status = "modified"
	Added     Status = "added"
	Untracked Status = "untracked"
	Deleted   Status = "deleted"
	Renamed   Status = "renamed"
)

type StatusOptions

type StatusOptions struct {
	// Limit caps the changes returned; zero or less returns all.
	Limit int
}

StatusOptions bound a status read.

Jump to

Keyboard shortcuts

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