Documentation
¶
Overview ¶
Package disk reports where the bytes WB causes to exist actually are, and how much room is left for the next one.
On 2026-09-17 this fleet's workstation reached 101 MB free of 150 GB. The first symptom was not a warning: it was a Go build failing in the linker with "no space left on device". Nothing had reported the growth, because nothing measured it. `wb fleet stats` counts repositories, worktrees and attention — all of them counts, none of them bytes.
The measurement that mattered was not the total. It was the split. Worktrees held 340 MB across the whole fleet; a single shared Go build cache held 22 GB; per-task scratch under /tmp held 46 GB in roughly 2,500 directories whose owning tasks had long finished. Anyone reasoning from "worktrees are the big thing WB creates" would have cleaned the wrong 0.2%.
So this reports per category, and separates two numbers that a single "size" would conflate:
- apparent bytes, which is what each tree looks like on its own
- unshared bytes, which is what removing it would actually give back
Those differ sharply here. Git worktrees share objects with their canonical clone and pnpm hard-links every store entry into every consumer, so a report that only shows apparent size promises a reclaim that deleting cannot deliver. internal/diskusage already draws that distinction correctly across trees, and this package accounts every category through one shared walk so content linked into two categories is not counted twice.
Index ¶
Constants ¶
const DefaultMinimumAvailableRatio = 0.10
DefaultMinimumAvailableRatio is the headroom below which a report complains. A tenth of the volume is enough for a large link step and a test run; the incident this package exists for had 0.0007 left.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Category ¶
type Category struct {
Name string `yaml:"name" json:"name"`
// Kind separates what may be deleted freely from what may not:
// "cache" is regenerable, "scratch" belongs to a task, "worktree" may
// hold unlanded work, "state" is WB's own durable records.
Kind string `yaml:"kind" json:"kind"`
// Roots are the measured paths, absent ones omitted.
Roots []string `yaml:"roots" json:"roots"`
// ApparentBytes is what the trees look like in isolation.
ApparentBytes int64 `yaml:"apparent_bytes" json:"apparent_bytes"`
UnsharedBytes int64 `yaml:"unshared_bytes" json:"unshared_bytes"`
// Note explains anything a byte count alone would misrepresent.
Note string `yaml:"note,omitempty" json:"note,omitempty"`
}
Category is one accounted group of WB-attributable bytes.
type Filesystem ¶
type Filesystem struct {
Path string `yaml:"path" json:"path"`
// TotalBytes is the volume's size.
TotalBytes int64 `yaml:"total_bytes" json:"total_bytes"`
// UsedBytes is what is consumed by everything, not only by WB.
UsedBytes int64 `yaml:"used_bytes" json:"used_bytes"`
// AvailableBytes is what this user can still write, which on most
// filesystems is less than free: a reserve is held back for root.
AvailableBytes int64 `yaml:"available_bytes" json:"available_bytes"`
}
Filesystem is the capacity of the volume a path lives on.
func (Filesystem) AvailableRatio ¶
func (f Filesystem) AvailableRatio() float64
AvailableRatio is the share of the volume still writable, 0 when unknown.
type Options ¶
type Options struct {
// ProjectsRoot is the {org}/{repo} checkout root.
ProjectsRoot string
// WBHome is WB's own state directory; empty resolves to ~/.wb.
WBHome string
// SkipSizes reports the roots and the filesystem without walking trees.
// Measuring a 22 GB build cache costs minutes of IO, and the free-space
// figure alone is often the answer.
SkipSizes bool
// MinimumAvailableRatio raises a finding when headroom falls below it.
// Zero applies the default.
MinimumAvailableRatio float64
// FilesystemProbe overrides how the volume's total/available bytes are
// read. Nil uses the real platform statfs (filesystemFor). Tests that
// must not depend on the host's own free space at test time inject a
// fake here instead of asserting on whatever headroom this machine
// happens to have.
FilesystemProbe func(path string) (Filesystem, error)
}
Options configures a report.
type Report ¶
type Report struct {
Filesystem Filesystem `yaml:"filesystem" json:"filesystem"`
Categories []Category `yaml:"categories" json:"categories"`
// AttributedBytes is the unshared total across categories, measured in one
// walk so content shared between categories is counted once.
AttributedBytes int64 `yaml:"attributed_bytes" json:"attributed_bytes"`
// Findings are conditions worth acting on, most urgent first.
Findings []string `yaml:"findings,omitempty" json:"findings,omitempty"`
// Skipped records roots that could not be measured, so a small total is
// never silently mistaken for a tidy machine.
Skipped []string `yaml:"skipped,omitempty" json:"skipped,omitempty"`
}
Report is one machine's accounting.
Source Files