repostatus

Documentation

Overview

Package repostatus answers what repository the shell is standing in, from a resident cache that a filesystem watch keeps honest.

It is a **shell capability and not a theme**, which is #1314's whole argument: a prompt is only as fast as the slowest thing it asks about, and in practice that is repository status. Making it fast once makes every prompt fast — a hand-written parameter, a cross-shell prompt, and this tree's own theme engine alike — rather than making one theme fast.

What it answers, and what it deliberately does not

The branch, or the short commit of a detached head, and whether an operation is half-finished. Those are a handful of stats and one small read, which is why they can be answered on the way to drawing a prompt.

**Not the counts** — modified, untracked, ahead, behind. Those need a full index-versus-working-tree walk, which is the expensive half and the reason every fast prompt in existence either caches it or hands it to a separate process. docs/spec/prompt-theme.md says what a prompt with no scanner attached shows: the branch and no counts, and it never waits for either. This is that, and the scanner is the first real job for the plugin segment role the spec reserves.

Watched, not polled

A poller either burns a core or serves a stale answer. So a repository is watched — internal/fswatch, written against the standard library because this module links nothing outside itself — and a change wakes a background refresh that publishes when the answer is different. That is what redraws a prompt somebody is sitting in front of when a branch moves in another terminal.

Where a watch cannot be had, the answer degrades to something stated rather than to something silently stale: every lookup re-stats the two files that would change the answer, so a change is seen at the next prompt rather than immediately, and Trouble says so out loud. A prompt that confidently shows the wrong branch is the worst failure this repository has, and "one prompt late" is a different thing from "wrong".

Index

• type Cache
  • func New(publish func()) *Cache
  • func (c *Cache) Close() error
  • func (c *Cache) Status(dir string) (Status, bool)
  • func (c *Cache) Trouble() string
  • func (c *Cache) Watching() bool
• type Status
  • func (s Status) Detached() bool

Types

type Cache

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

Cache is the resident per-repository cache.

One per session. It holds an answer per repository root rather than per directory, because moving between two directories of one repository does not change the answer and should not cost a second read.

func New

func New(publish func()) *Cache

New returns a cache that calls publish when a repository it is watching has changed into something a prompt would draw differently.

publish may be nil, which is a cache that answers from a lookup and never redraws anything — what a caller with no way to redraw should get.

A nil *Cache is usable and answers "not in a repository" to everything. A prompt is drawn from whatever is wired into it, and a caller that was built without this one must get an answer rather than a panic on the most visible line on the screen.

func (*Cache) Close

func (c *Cache) Close() error

Close stops the watch. Answers afterwards are read fresh rather than cached, because a cache nothing is invalidating is the silently-stale answer this package exists to avoid.

func (*Cache) Status

func (c *Cache) Status(dir string) (Status, bool)

Status answers for a directory, and never blocks on anything but the stats it takes itself.

The second value is false where the directory is not in a repository, which is a segment declining rather than an error: most directories are not in one and a prompt should cost nothing there.

func (*Cache) Trouble

func (c *Cache) Trouble() string

Trouble is why there is no watch, or empty where there is one or where nothing has needed one yet.

func (*Cache) Watching

func (c *Cache) Watching() bool

Watching reports whether a filesystem watch is keeping the answers honest, which is the difference between a prompt that is redrawn when a branch moves and one that catches up at the next prompt.

type Status

type Status struct {
	// Root is the working tree's top, and Git is the directory holding the
	// repository's own files — the same path except in a linked working tree
	// or a submodule, where `.git` is a file naming somewhere else.
	Root string
	Git  string

	// Branch is the branch a commit would land on, empty when the head is
	// detached. Commit is the short form of what a detached head points at.
	Branch string
	Commit string

	// Operation is a half-finished thing the repository is in the middle of
	// — a merge, a rebase, a cherry-pick, a revert, a bisect — and empty
	// otherwise. It is the state a person most needs a prompt to tell them
	// about, because it is the one they can forget they are in.
	Operation string
}

Status is what this package knows about the repository a directory is in.

func (Status) Detached

func (s Status) Detached() bool

Detached reports whether the head points at a commit rather than a branch.