gitinfo

Documentation

Overview

Package gitinfo reads the small set of repository facts Quil shows beside a pane: which branch, whether the checkout is a linked worktree, and how far it has diverged from its upstream.

Pure and stdlib-only, a sibling of gitdiscover and kubediscover. It shells out to git plumbing rather than parsing .git by hand — the formats it would have to parse (packed refs, worktree files, HEAD indirection) are exactly the ones git changes between releases, and the plumbing commands are the stable interface. Every call is a read; nothing here can modify a repository.

`git status --porcelain` is deliberately absent. It is the one call that can take seconds on a large repository without fsmonitor, and it would need its own cadence, config gate and timeout budget.

Index

• func Dirs(ctx context.Context, dir string) (gitDir, commonDir string, ok bool)
• type Info
  • func Probe(ctx context.Context, dir string) (Info, bool)
  • func (i Info) Empty() bool

Functions

func Dirs

func Dirs(ctx context.Context, dir string) (gitDir, commonDir string, ok bool)

Dirs resolves a directory's repository identity: the absolute per-checkout git dir and the repository-wide common dir. They differ exactly when this checkout is a linked worktree.

The PER-CHECKOUT dir is the cache key a caller wants, not the common one. Every linked worktree of a repository shares the common dir while sitting on its own branch — which is the entire reason someone creates one — so keying a branch cache on the common dir would report every worktree as being on whichever branch was probed first. Keying on the per-checkout dir still collapses the common case, N panes in different subdirectories of one checkout, to a single probe.

ok is false for a directory that is not inside a repository at all. Callers are expected to remember that, because re-probing a non-repository costs the same as probing a real one.

Types

type Info

type Info struct {
	// Branch is the checked-out branch name, or "" when HEAD is detached.
	// Detached is tracked separately because "" alone cannot distinguish a
	// detached HEAD from a probe that did not run.
	Branch   string
	Detached bool

	// LinkedWorktree reports a checkout created by `git worktree add`, where
	// the per-worktree git dir differs from the repository's common dir.
	LinkedWorktree bool

	// WorktreeName names that linked worktree; empty on the main checkout.
	//
	// Taken from the per-checkout git dir's basename, which git spells
	// <common>/worktrees/<name> — so it costs no command of its own, which is
	// what lets the sidebar show it without widening this package's fixed
	// three-calls-per-checkout budget.
	//
	// It is git's own identifier for the worktree rather than the checkout
	// DIRECTORY's basename, and the two can differ when git disambiguates a
	// name collision. The identifier is the more useful of the pair: it is
	// what `git worktree list` prints and what `git worktree remove` accepts.
	WorktreeName string

	// Ahead/Behind count commits relative to the tracking branch. Meaningful
	// only when HasUpstream; a branch with no upstream is not "0 ahead, 0
	// behind", it is unmeasured.
	HasUpstream bool
	Ahead       int
	Behind      int
}

Info is one checkout's state. The zero value means "nothing known", which is what a non-repository and a failed probe both produce — callers distinguish them by the ok/error return, not by inspecting fields.

func Probe

func Probe(ctx context.Context, dir string) (Info, bool)

Probe reads a checkout's branch and divergence. The caller supplies the timeout via ctx; every command shares it, so a repository on a mount that stopped answering costs one budget rather than one per command.

func (Info) Empty

func (i Info) Empty() bool

Empty reports whether the probe found nothing worth rendering.