Timber Survey
Timber Survey is a command-line inventory of a full disk. It walks a tract (your home folder by default), measures every folder by the blocks it holds on disk, and sorts the large ones into two lists: TIMBER, folders that something beside them proves can be grown again, each with one rm -rf line you may paste, and STANDING, the large folders nothing can grow again, listed with no command and no total. Build it with Go 1.22 or later, standard library only: go build -o timber-survey ., then run ./timber-survey ~ or ./timber-survey ~/code --min 2G. Its input is your real filesystem: folder sizes from lstat, last-modified dates, the manifests and lockfiles beside each candidate, and the free space the volume reports. It runs on Linux and macOS. Reads only. Removes nothing.
Usage
timber-survey [tract] [--min SIZE]. Reads only. Removes nothing.
SIZE is 500M, 2G, 1.5G or plain bytes; the default is 500M. Progress goes to stderr only when stderr is a terminal; stdout carries only the sheet. Exit code 2 means a bad argument or No such tract.
The proof rule
A folder is timber only when something proves it can be regrown.
| Folder name | Proof required | Note when proof is thin |
|---|---|---|
| node_modules | package.json beside it | no lockfile: no lockfile: regrows, not identically |
| .next | package.json beside it | |
| target | Cargo.toml beside it | no Cargo.lock: same note |
| dist, build | package.json with a scripts.build entry, and a .gitignore line naming the folder | |
| .venv, venv | one of pyproject.toml, requirements.txt, uv.lock, Pipfile beside it | |
| Pods | Podfile beside it | no Podfile.lock: same note |
| __pycache__ | none (the interpreter rewrites it) | |
| DerivedData | path ends in Library/Developer/Xcode/DerivedData | |
| any | a CACHEDIR.TAG inside whose first line is the cache directory signature | self-declared cache |
The tag is the fallback when a folder's own row is missing or fails. uv writes a CACHEDIR.TAG into every virtual environment it makes, so a lone .venv made by uv is timber with that note, while one made by python3 -m venv with no manifest beside it is standing.
A folder with a timber name and no proof is listed as standing with its reason (no package.json beside it). The survey never looks inside timber-named folders for further rows. Standing sizes exclude any timber inside them, and say so (timber inside not counted). When one child holds most of a large folder and the rest is under the threshold, the child is listed instead of the folder. The tract itself is never a row. Hard links count once, symbolic links are never followed, other devices are not entered (on a Mac /Volumes and /System/Volumes are skipped), and folders that cannot be read are counted in the header under Not read:.
A series
timber-survey ~ > "$(date +%F).txt"
Keep the sheets. diff two of them to see what was felled and what grew back. Apart from the Surveyed:, Volume: and Free after felling lines, every line that differs is a folder that was felled, grew back, grew or was touched.
Checks
go test ./... builds a temporary tree of real files and checks every classification case. bash qa/accept.sh runs all acceptance checks from CARD.md on Linux (it needs tmux, strace, script, uv and python3) and writes pane captures to out/panes/; uv run --with playwright python qa/shots.py renders them into shots/ (it needs Playwright's Chromium, uv run --with playwright playwright install chromium). Results are in BUILD.md.
Colophon
Form 1 of the stand inventory series, issued by normal is dead. Typed in your terminal's own monospace, one sheet per run, no colour, because the colour of your terminal is not ours to decide. The office measures and records. Felling is done by hand, by the holder of the tract, one line at a time. Standing items are recorded for completeness and are not scheduled for anything.
Files
- README.md
- go.mod
- main.go
- main_test.go
- out/fixture-sheet.txt
- out/panes/empty-132x44.txt
- out/panes/empty-48x50.txt
- out/panes/errors-132x44.txt
- out/panes/errors-48x50.txt
- out/panes/fixture-132x44.txt
- out/panes/fixture-48x50.txt
- out/panes/fixture-80x40.txt
- out/panes/progress-132x44.txt
- out/panes/progress-48x50.txt
- out/panes/stand-132x44.txt
- out/panes/stand-48x50.txt
- out/panes/stand-80x40.txt