init
This commit is contained in:
24 files changed
+3822
No files matched your search
@@ -0,0 +1,103 @@
|
||||
# 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;
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user