gitx

Documentation

Overview

Package gitx exposes read-only git awareness (branch, working-tree status, recent commits, tracked files) behind a small Client interface. The default implementation shells out to the git CLI, which is the fast path for real repos and is universally available for git-native workflows. When no git binary is present, a null client degrades gracefully (IsRepo == false).

Index

• type Branch
• type Change
• type Client
  • func New(repoRoot string) Client
• type Commit
• type Status

Types

type Branch

type Branch struct {
	Name       string    // %(refname:short), e.g. "feature/login"
	SHA        string    // %(objectname), the tip commit SHA — pin this for tree reads
	CommitDate time.Time // %(committerdate), tip commit time
}

Branch is a local branch head with its tip commit pinned. The SHA is captured at enumeration time so callers can read that branch's tree via an immutable commit object — a branch deleted/renamed/moved afterwards cannot break a later ls-tree/show against the pinned SHA.

type Change

type Change struct {
	Path string `json:"path"`
	Code string `json:"code"` // porcelain code, e.g. "M", "A", "??"
}

Change is one entry in the working-tree status.

type Client

type Client interface {
	IsRepo(ctx context.Context) bool
	Snapshot(ctx context.Context, commitLimit int) Status
	Files(ctx context.Context) []string

	// Branches lists local branch heads (refs/heads) with pinned tip SHAs.
	Branches(ctx context.Context) []Branch
	// ListTreeFiles lists file paths under pathspec in the committed tree at
	// rev (typically a pinned SHA), without checking anything out.
	ListTreeFiles(ctx context.Context, rev, pathspec string) []string
	// ShowFile returns the bytes of one file at rev. ok is false when the file
	// or rev does not exist.
	ShowFile(ctx context.Context, rev, path string) (content []byte, ok bool)

	// Log returns commits that touch pathspec OR whose message contains grep
	// (either may be empty), de-duplicated by commit and newest first, capped
	// at limit.
	Log(ctx context.Context, pathspec, grep string, limit int) []Commit
}

Client reads git state for a repository. Methods never error; problems yield an empty/not-a-repo Status (or an empty slice / ok=false for the tree readers).

func New

func New(repoRoot string) Client

New returns a git client anchored at repoRoot. If the git binary is missing, a null client is returned.

type Commit

type Commit struct {
	Hash    string    `json:"hash"`
	Subject string    `json:"subject"`
	Author  string    `json:"author"`
	When    time.Time `json:"when"`
}

Commit is a recent commit.

type Status

type Status struct {
	IsRepo    bool     `json:"isRepo"`
	Branch    string   `json:"branch"`
	Dirty     bool     `json:"dirty"`
	Changes   []Change `json:"changes"`
	Truncated bool     `json:"truncated"`
	Commits   []Commit `json:"commits"`
}

Status is a snapshot of git awareness.