Files
2026-10-28 08:00:16 +05:30

104 lines
5.5 KiB
Markdown

# i-am-gcroot
List, filter and delete Nix garbage collector roots from a TUI, an optional web UI, or the command line.
```
nix run github:illustris/i-am-gcroot # TUI
nix run . -- --web # TUI + web UI on 127.0.0.1:8377
nix run . -- list -q 'under:/tmp older:7d' --sizes
```
## What it finds
| Kind | What it is | Delete does |
|---|---|---|
| `indirect` | a link outside the gcroots tree (`./result`, `.gcroots/foo`) registered via `/nix/var/nix/gcroots/auto` | removes the link (and the `auto/` entry if writable; `nix-store --gc` prunes it otherwise) |
| `dangling` | an `auto/` entry whose link is already gone | removes the `auto/` entry (needs root) |
| `profile` | a profile generation, `<profile>-<N>-link`, system or user | `nix-env --profile <p> --delete-generations N` |
| `direct` | any other symlink in `/nix/var/nix/gcroots` | removes the link |
| `runtime` | store paths held by running processes (`/proc/...`), grouped per PID | never deletable; hidden unless asked for |
Protected roots (marked `!`) are refused unless `--force` is given: the current generation of every profile, and `gcroots/current-system` / `gcroots/booted-system`.
Only symlinks are ever removed. Nothing in `/nix/store` is touched until you run GC: either a full `nix-store --gc` (`g` in the TUI, the "run gc" button, `i-am-gcroot gc`) or a targeted collect right after deleting (`X` in the TUI, "delete + collect", `rm -c`).
Targeted collect takes the closures of the roots just deleted, subtracts everything still reachable from any GC root (including runtime roots), and runs `nix-store --delete` on the rest. Nix re-checks liveness itself, so a path that turns out to be alive (for example through `keep-derivations`) is kept and reported. It takes tens of seconds rather than a walk of the whole store.
Roots that nix creates for its own caches (anything under `.cache/nix/`, like `~/.cache/nix/flake-registry.json`) are hidden by default. Show them with `h` in the TUI, the "hidden" checkbox, `--all`, or the `is:hidden` query term.
Closure sizes come from `nix path-info -S` and load in the background. The "up to" figure for a selection is the sum of closures; shared paths may stay alive through other roots, so the real amount freed is usually less.
## Filter syntax
Terms are whitespace separated and ANDed. Prefix any term with `-` to negate it.
| Term | Matches |
|---|---|
| `foo` | case-insensitive substring of link, target, via or command |
| `/re/` | regex over the same fields (no spaces, use `\s`; terms with more than two `/` are substrings) |
| `kind:indirect,dangling` | kinds (prefixes like `kind:prof` work) |
| `owner:me`, `owner:alice`, `owner:1000` | owner of the link |
| `under:/tmp/claude-` | link starts with this prefix |
| `older:30d`, `newer:2h` | link mtime (`s m h d w y`) |
| `size>1G`, `size<10M` | closure size (`K M G T`) |
| `is:protected`, `is:current`, `is:dangling`, `is:hidden` | flags (`is:hidden` also makes hidden roots visible) |
## TUI keys
| Key | Action |
|---|---|
| `j/k`, arrows, `pgup/pgdn`, `home/end` | move |
| `space` / `x` | mark / unmark |
| `a` / `A` | mark all shown (non-protected) / clear marks |
| `d` | delete marked roots (or the one under the cursor), with confirmation |
| `X` | delete, then garbage collect only the store paths those roots kept alive |
| `D` | dry run |
| `g` | run `nix-store --gc` |
| `/` | edit filter (`enter`/`esc` to leave, `esc` again clears it) |
| `1`-`5`, `0` | toggle kinds, reset kinds |
| `h` | show/hide nix cache roots |
| `s` / `S` | cycle sort key (age, size, target, kind, link) / reverse |
| `enter` | details |
| `R` | full results of the last delete or dry run |
| `r` | rescan |
| `?` | help |
Below the key hints, an activity line shows the running operation with a timer, then a one-line outcome (failures included); `R` shows the per-root details. The list is rescanned from disk after every delete.
## CLI
```
i-am-gcroot [tui] [-q QUERY] [--web] [--addr ADDR] [--no-auth] [--runtime] [--force]
i-am-gcroot list [-q QUERY] [--kind K,..] [--sort KEY] [--desc] [--sizes] [--json] [--runtime] [--all]
i-am-gcroot rm [-n] [-y] [-c] [--force] [--all] (-q QUERY | LINK...)
i-am-gcroot gc
i-am-gcroot web [--addr ADDR] [--no-auth] [--force] [--runtime]
```
`rm` asks for confirmation unless `-y`; `-n` is a dry run; `-c` runs the targeted collect afterwards; `--all` lets `-q` match hidden roots (explicit link arguments always work).
## Web UI
`i-am-gcroot web` (headless) or `--web` alongside the TUI. It binds to `127.0.0.1:8377` and generates a random token at startup; open the printed URL (`?token=...`), which sets a cookie. POST requests additionally require the token in an `X-Token` or `Authorization: Bearer` header (the page sends it), so a cross-site form cannot trigger deletes. `--no-auth` disables this; only use it on a trusted socket.
JSON API (with `Authorization: Bearer <token>`):
- `GET /api/roots?q=...&kind=indirect&kind=profile&sort=size&desc=1&hidden=1`
- `POST /api/delete` with `{"links": ["/home/me/result"], "dryRun": false, "collect": true}`, returns `{"results": [...], "collected": {...}}`
- `POST /api/gc`
## Permissions
Run as your user to manage your own roots. Root-owned roots (system profile generations, `auto/` entries of dangling roots, other users' links) fail with a hint to rerun under `sudo`. Runtime roots of other users' processes show as `{censored}` unless run as root.
## NixOS
```nix
{
inputs.i-am-gcroot.url = "github:illustris/i-am-gcroot";
# ...
imports = [ inputs.i-am-gcroot.nixosModules.default ];
programs.i-am-gcroot.enable = true;
}
```