git

Documentation

Overview

Package git wraps the handful of git commands live-pr needs by shelling out, rather than pulling in a full git library.

Index

• func CheckoutPullHead(branch string) error
• func CommonDir(dir string) (string, error)
• func CurrentBranch() (string, error)
• func DefaultBase() string
• func FetchPull(number int, base string) (string, string, error)
• func FileDiffRange(base, head string, paths ...string) (string, error)
• func HasChanges(base, head string) (bool, error)
• func HasUncommittedChanges() (bool, error)
• func IsAncestor(ancestor, descendant string) (bool, error)
• func MergeBase(base, head string) (string, error)
• func Push(branch string) error
• func RepoRoot() (string, error)
• func ResolveBase(base string) string
• func Revision(rev string) (string, error)
• func RevisionDistance(local, remote string) (ahead, behind int, err error)
• func Show(sha string) (string, error)
• type ChangeStats
  • func DiffStats(base, head string) (ChangeStats, error)
• type ChangedFile
  • func ChangedFilesRange(base, head string) ([]ChangedFile, error)
• type Commit
  • func Commits(base string) ([]Commit, error)
  • func CommitsRange(base, head string) ([]Commit, error)
• type LocalSnapshot
  • func CurrentLocalSnapshot() (LocalSnapshot, error)
• type LocalState
  • func CurrentLocalState() (LocalState, error)
• type MergeReadiness
  • func CheckMergeReadiness(base, head string) (MergeReadiness, error)
• type RevisionRelation
  • func CompareRevisions(local, remote string) (RevisionRelation, error)
• type WorktreeSummary
  • func WorktreeStatus() (WorktreeSummary, error)
  • func (s WorktreeSummary) Total() int

Functions

func CheckoutPullHead

func CheckoutPullHead(branch string) error

CheckoutPullHead checks out the head branch of a same-repository pull request with plain git, mirroring gh pr checkout's non-fork path: fetch the branch from origin, then switch to a local tracking branch, fast-forwarding one that already exists (a diverged branch fails the same way it does under gh). Fork heads need gh's cross-repository remote wiring and must not come here.

func CommonDir

func CommonDir(dir string) (string, error)

CommonDir returns the absolute path of the repository's common .git directory for the checkout at dir. Linked worktrees share it with their main checkout, so it identifies the repository across worktrees.

func CurrentBranch

func CurrentBranch() (string, error)

CurrentBranch returns the checked-out branch name (e.g. "main", "feature/x").

func DefaultBase

func DefaultBase() string

DefaultBase returns the branch to compare against: the remote's default (origin/HEAD, e.g. "origin/main") when known, else a local main/master, falling back to "main".

func FetchPull

func FetchPull(number int, base string) (string, string, error)

FetchPull fetches a GitHub pull ref and its base without changing HEAD, the index, or the worktree. It returns the namespaced local head ref.

func FileDiffRange

func FileDiffRange(base, head string, paths ...string) (string, error)

FileDiffRange returns the colorized base...head patch for selected paths. An empty head compares through the working tree and includes selected untracked files without changing the index.

func HasChanges

func HasChanges(base, head string) (bool, error)

HasChanges reports whether base...head contains any changed paths.

func HasUncommittedChanges

func HasUncommittedChanges() (bool, error)

HasUncommittedChanges reports whether the index, worktree, or untracked files differ from HEAD.

func IsAncestor

func IsAncestor(ancestor, descendant string) (bool, error)

IsAncestor reports whether ancestor is reachable from descendant.

func MergeBase

func MergeBase(base, head string) (string, error)

MergeBase returns the best common ancestor of two revisions.

func Push

func Push(branch string) error

Push pushes the branch to origin, setting upstream. A stalled SSH/HTTPS transport must not hang the caller forever, so the push is bounded; the limit is longer than FetchPull's because a push carries data up.

func RepoRoot

func RepoRoot() (string, error)

RepoRoot returns the absolute path to the current repository's top level.

func ResolveBase

func ResolveBase(base string) string

ResolveBase turns a GitHub base name into the freshest local Git revision, preferring its origin remote-tracking ref when available.

func Revision

func Revision(rev string) (string, error)

Revision resolves rev to its full object ID.

func RevisionDistance

func RevisionDistance(local, remote string) (ahead, behind int, err error)

CompareRevisions classifies local relative to remote by graph reachability. RevisionDistance returns commits unique to local and remote.

func Show

func Show(sha string) (string, error)

Show returns the full `git show` for a commit (stat + colorized patch), capped to a sane number of lines.

Types

type ChangeStats

type ChangeStats struct {
	Files, Additions, Deletions int
}

ChangeStats summarizes a diff range for PR list metadata.

func DiffStats

func DiffStats(base, head string) (ChangeStats, error)

DiffStats returns file and line counts for the given range. An empty head compares the working tree against base. Binary files count toward Files but not line totals.

type ChangedFile

type ChangedFile struct {
	Status  string
	Path    string
	OldPath string
	// Fingerprint identifies this file's diff content. It changes only when
	// this file's own diff changes, so reviewed marks survive commits that
	// touch other files.
	Fingerprint string
}

ChangedFile is one entry in base...HEAD.

func ChangedFilesRange

func ChangedFilesRange(base, head string) ([]ChangedFile, error)

ChangedFilesRange returns changed paths in the given range. An empty head compares the working tree against base and includes untracked files.

type Commit

type Commit struct {
	SHA     string
	Date    string // "2006-01-02T15:04"
	Subject string
	Body    string
}

Commit is a git commit reduced to what the timeline needs.

func Commits

func Commits(base string) ([]Commit, error)

Commits returns the commits in base..HEAD, oldest first.

func CommitsRange

func CommitsRange(base, head string) ([]Commit, error)

CommitsRange returns commits in base..head, oldest first.

type LocalSnapshot

type LocalSnapshot struct {
	State    LocalState
	Worktree WorktreeSummary
}

func CurrentLocalSnapshot

func CurrentLocalSnapshot() (LocalSnapshot, error)

CurrentLocalSnapshot derives branch, fingerprint, and worktree counts from one porcelain-v2 scan.

type LocalState

type LocalState struct {
	Branch      string
	Fingerprint string
}

LocalState identifies the checked-out branch and every local Git input that can change the review (HEAD, index, worktree, and untracked paths).

func CurrentLocalState

func CurrentLocalState() (LocalState, error)

type MergeReadiness

type MergeReadiness struct {
	Behind        int
	ConflictFiles []string
}

MergeReadiness describes how far head trails base and which paths conflict.

func CheckMergeReadiness

func CheckMergeReadiness(base, head string) (MergeReadiness, error)

CheckMergeReadiness simulates merging head into base without touching HEAD, the index, or the worktree.

type RevisionRelation

type RevisionRelation uint8

RevisionRelation describes local relative to a published revision.

const (
	RevisionUnknown RevisionRelation = iota
	RevisionSynced
	RevisionLocalAhead
	RevisionRemoteAhead
	RevisionDiverged
)

func CompareRevisions

func CompareRevisions(local, remote string) (RevisionRelation, error)

type WorktreeSummary

type WorktreeSummary struct {
	Staged, Unstaged, Untracked int
}

func WorktreeStatus

func WorktreeStatus() (WorktreeSummary, error)

WorktreeStatus summarizes index, worktree, and untracked entries.

func (WorktreeSummary) Total

func (s WorktreeSummary) Total() int