worktrees

Documentation

Overview

Package worktrees finds the linked git worktrees under the configured roots and tells a finished one (its pull request merged or closed) from one that still holds work. A finished worktree that holds nothing but build output is removed whole; one that also holds uncommitted changes or unpushed commits keeps them and loses only its build output, as does an unfinished one left untouched for the grace. A live session's worktree and a locked one are never touched. A worktree whose gitfile names a repository that no longer exists is an orphan (Dangling).

Index

• Constants
• Variables
• func Dangling(dir string) bool
• func Find(roots []string) []string
• func RemoveAll(path string) error
• func RepoOf(url string) string
• func Size(path string) int64
• func Writable(path string) error
• type Git
• type Tree
  • func Inspect(ctx context.Context, git Git, dir string) (Tree, error)
  • func (t Tree) HeadBranch() string
• type Verdict
  • func Decide(t Tree, pull *github.HeadPull, live, pushed bool, now time.Time) Verdict

Constants

const (
	Keep   = "keep"
	Remove = "remove"
	// Clean removes only the build output of a finished worktree whose
	// real work stays.
	Clean = "clean"
)

The actions on a worktree.

const (
	KeptLive     = "live"
	KeptLocked   = "locked"
	KeptNoOrigin = "no GitHub origin"
	KeptDetached = "detached HEAD"
	KeptNoPull   = "no pull request"
	KeptOpen     = "pull request open"
	KeptClosed   = "closed within the grace"
	KeptTouched  = "touched within the grace"
	KeptWork     = "holding only work"
)

The kinds of kept worktrees.

const DetachedIdle = 72 * time.Hour

DetachedIdle is how long a worktree on a detached HEAD (a release's or a pull request's proof checkout) must be untouched before it counts as finished: no pull request says when its work ended.

const Grace = 6 * time.Hour

Grace is how long a pull request must be closed, and a worktree's HEAD and index untouched, before the worktree counts as finished: its worker may still prove the merge from it.

Variables

var Regenerable = []string{
	"node_modules", "dist", "dist-types", "bin", "build", "out", "target",
	".turbo", ".next", ".cache", ".yarn/cache", "coverage",
	"__pycache__", ".pytest_cache", ".venv",
}

Regenerable are the directories a build, an install or a test run writes and the next one writes again, by name or, with a slash, by their last path elements: untracked or ignored, one of these is build output wherever it lies.

Functions

func Dangling

func Dangling(dir string) bool

Dangling reports whether dir is a linked worktree whose gitfile names a gitdir that no longer exists: its repository went, or pruned it, and git cannot read it.

func Find

func Find(roots []string) []string

Find lists the linked worktrees under roots, sorted; a root that does not exist has none. It does not look inside a worktree for more.

func RemoveAll

func RemoveAll(path string) error

RemoveAll removes path and everything under it, read-only directories included (Writable).

func RepoOf

func RepoOf(url string) string

RepoOf is the owner/repo of a GitHub remote URL, "" for another host.

func Size

func Size(path string) int64

Size is the disk space in bytes the files under path take, as du counts it (the apparent size where the platform says no blocks).

func Writable

func Writable(path string) error

Writable gives the owner write and search permission on every directory under path, path included, as go clean -modcache does: a read-only one (a Go module cache copy, envtest's binaries under go/bin/k8s) refuses the unlink of what it holds, while a read-only file in a writable directory unlinks. Symbolic links are not followed, path itself included, and no change reaches outside path.

Types

type Git

type Git func(ctx context.Context, dir string, args ...string) ([]byte, error)

Git runs git in dir and returns its standard output.

type Tree

type Tree struct {
	Dir string
	// Repo is the GitHub repository of its origin remote (owner/repo), ""
	// for none; Branch the branch checked out, "" when HEAD is detached;
	// Pushed the branch on origin it tracks, "" for none.
	Repo, Branch, Pushed string
	Head                 string
	// Locked says git worktree lock protects it.
	Locked bool
	// Work are the uncommitted changes that are real work: tracked
	// changes and untracked paths that are no build output.
	Work []string
	// Build are the untracked or ignored paths (git status's units,
	// directories end in /) that are build output: Regenerable ones.
	Build []string
	// Unpushed are the commits on HEAD no remote-tracking branch has.
	Unpushed int
	// Touched is when its HEAD, reflog or index last changed.
	Touched time.Time
}

Tree is one linked worktree as git reports it.

func Inspect

func Inspect(ctx context.Context, git Git, dir string) (Tree, error)

Inspect reads dir's state through git. git status runs without its optional index refresh, so the look changes nothing Touched reads.

func (Tree) HeadBranch

func (t Tree) HeadBranch() string

HeadBranch is the branch a pull request of t names as its head: the branch on origin it tracks, unless that is the default branch it was cut from, else the branch checked out.

type Verdict

type Verdict struct {
	Action string
	Why    string
	Kept   string
}

Verdict is what happens to a worktree, and why; Kept is the kind of a kept one.

func Decide

func Decide(t Tree, pull *github.HeadPull, live, pushed bool, now time.Time) Verdict

Decide judges t: live says a session or a process works in it, pull is the newest pull request its branch opened (nil for none), pushed says its unpushed commits are the pull request's own (its head, or before it).

A worktree kept for any other reason than a live session or a lock, and untouched Grace, still loses its build output (Clean, Kept naming why it stays): the next build writes it again, and git state, branch and commits stay.