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 ¶
- Variables
- func BlobHash(content []byte) string
- func LineChanges(old, new []byte) (added, deleted int)
- type Author
- type Blob
- type BranchList
- type BranchRange
- type BranchRef
- type Change
- type Changes
- type Commit
- type CommitChanges
- type Entry
- type Hash
- type History
- type LogOptions
- type Range
- type Repository
- func (r *Repository) Branch() string
- func (r *Repository) BranchCompare(ctx context.Context, base, head string) (BranchRange, error)
- func (r *Repository) BranchFiles(ctx context.Context, base, head string, limit int) (BranchRange, CommitChanges, error)
- func (r *Repository) BranchLookup(ctx context.Context, base, head, name, oldPath string) (BranchRange, Change, error)
- func (r *Repository) Branches(limit int) (BranchList, error)
- func (r *Repository) Close() error
- func (r *Repository) CommitBlob(hash Hash, name string) (Blob, error)
- func (r *Repository) CommitFiles(ctx context.Context, hash Hash, limit int) (CommitChanges, error)
- func (r *Repository) CommitLookup(ctx context.Context, hash Hash, name, oldPath string) (Change, error)
- func (r *Repository) DefaultBase() (string, error)
- func (r *Repository) Entries(changes []Change) ([]Entry, error)
- func (r *Repository) HeadBlob(name string) (Blob, error)
- func (r *Repository) Log(ctx context.Context, options LogOptions) (History, error)
- func (r *Repository) Lookup(ctx context.Context, name, oldPath string) (Entry, error)
- func (r *Repository) ParentBlob(hash Hash, name string) (Blob, error)
- func (r *Repository) RangeFiles(ctx context.Context, from, to Hash, limit int) (CommitChanges, error)
- func (r *Repository) RangeLookup(ctx context.Context, from, to Hash, name, oldPath string) (Change, error)
- func (r *Repository) Stack(ctx context.Context, base string) (Stack, error)
- func (r *Repository) Status(ctx context.Context, options StatusOptions) (Changes, error)
- type Stack
- type StackLayer
- type Status
- type StatusOptions
Constants ¶
This section is empty.
Variables ¶
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 = errors.New("not a change") )
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 LineChanges ¶
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 Blob ¶
type Blob struct {
Size int64
// contains filtered or unexported fields
}
Blob is a HEAD file's content, sized before it is read.
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 ¶
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 ¶
Hash is a full commit hash; the zero Hash is unset. It keeps go-git types inside this package.
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 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 ¶
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 ¶
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 StatusOptions ¶
type StatusOptions struct {
// Limit caps the changes returned; zero or less returns all.
Limit int
}
StatusOptions bound a status read.