gitworktree

Documentation

Overview

Package gitworktree performs the repository WRITES Quil needs to give a pane its own linked worktree, plus the listing that offers the existing ones.

It is deliberately a separate package from gitinfo rather than a few more functions in it. gitinfo's package documentation states that every call is a read and nothing there can modify a repository — and that is load-bearing rather than descriptive: the daemon runs gitinfo.Probe on a ticker against every pane's checkout, so a package that gains the ability to write is one careless refactor away from a ticker that writes. Keeping the two apart makes that mistake need an import to happen, which is a thing a reviewer can see.

Pure and stdlib-only, a sibling of gitinfo, gitdiscover and kubediscover. It shells out to git plumbing rather than manipulating .git by hand — creating a worktree means writing a gitdir file, an admin directory under worktrees/<name>, and a checked-out tree, and getting any of it subtly wrong produces a repository git itself cannot repair.

Index

• func Add(ctx context.Context, repo, path, branch string) error
• type Worktree
  • func List(ctx context.Context, dir string) ([]Worktree, error)

Functions

func Add

func Add(ctx context.Context, repo, path, branch string) error

Add creates a linked worktree at path, checking out a NEW branch off the repository's current HEAD. repo is the directory the command runs in.

There is deliberately no force option and no --force in the argv. Every refusal git can raise here is a fact the user needs — the path is occupied, the branch already exists, the branch is checked out in another worktree, the repository has no commits to branch from — and forcing past any of them lands a pane on top of a checkout something else is using. The error is returned with git's own stderr attached, because "already used by worktree '/x/feat-y'" tells the user which pane to go look at and no message this package could invent would.

Types

type Worktree

type Worktree struct {
	// Path is the working directory, absolute, as git reports it.
	Path string
	// Branch is the checked-out branch with the refs/heads/ prefix stripped.
	// Empty when Detached or Bare.
	Branch   string
	Detached bool
	// Main marks the repository's primary checkout — the first block git
	// prints. It is where a NEW worktree's path is derived from, and it is the
	// one entry that must never be offered as somewhere to attach.
	Main bool
	// Locked and Prunable mark entries git will refuse to operate on.
	Locked   bool
	Prunable bool
	// Bare marks a repository with no working tree. Only ever true on the main
	// entry, and it cannot host a pane.
	Bare bool
}

Worktree is one entry of `git worktree list --porcelain`.

Locked and Prunable are carried rather than filtered because both describe an entry that LOOKS attachable and is not: a prunable worktree's directory is gone, and a locked one refuses operations. Dropping them would hand the caller a shorter list with no way to explain the absence, so a pane could be offered a directory that cannot host it.

func List

func List(ctx context.Context, dir string) ([]Worktree, error)

List reports the worktrees of the repository containing dir, main checkout first. The caller supplies the timeout via ctx.

A directory outside any repository is NOT an error: the setup dialog asks about every directory the user browses to, and most are not repositories, so treating that as a failure would put an error on screen for the ordinary case. It returns no entries, which is the same shape the caller renders for a repository with nothing to attach to.

That collapse is deliberately narrow: a plain non-zero exit from `git worktree list` — the shape "not a repository" actually takes — is the only case folded into (nil, nil). A missing git binary (exec.ErrNotFound) and a call that ran out of time (ctx.Err() != nil) are returned as errors instead, or a missing binary, a corrupt repository and a permissions error would all render the same confidently-wrong "not a git repository" the caller shows for the genuine case.