104 lines
5.5 KiB
Markdown
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;
|
|
}
|
|
```
|