docs(troubleshooting): the disk-full page says which repository owns the space #1744

Merged
jaylouisw merged 1 commit from fix/1116-2235 into main 2026-11-16 22:47:13 +00:00
Owner

docs/FORGE_TROUBLESHOOTING.md told a reader that the volume was full and what four symptoms it produces. It never said how to find what filled it, which is the measurement that took #1507 four days: GET /api/v1/repos/search?sort=size returned 46.2 GiB in one private repository against 0.0 GiB in this one (96% of the instance).

The added section also carries the distinction that decides what reclaims it: stored size is not tree size. packetforge-firmware holds 46.2 GiB against a tip of 6.4 MB across 396 blobs, one branch and no tags - so the dumps are previous commits, and git gc (and every 204-answering housekeeping task) could never have freed them. count-objects -vH against ls-tree -r -l HEAD is the two-command split.

Every command in the section was run before it was written down, in the shell that prints it.

The ways out - history rewrite, moving the repository off the volume, deleting it - are decisions about content, so they stay with #1507 and this does not close it.

Tests: new test/forge-space-accounting.test.js, 10 assertions; 10 failed against the previous page and 10 pass against this one, so the section cannot be deleted back to a df -h page. scripts/syntax-check.js 365 files all OK, check-control-bytes clean, check-canonical-urls 2979 files OK, run-tests --filter=doc 5 suites / 126 assertions, --filter=canonical 52 assertions, all green. No engine code touched.

Found while running the gates, not fixed here (one issue per run): a node --check child that fails to start on this Windows host (0xC0000142, STATUS_DLL_INIT_FAILED under load) is counted by scripts/syntax-check.js as a syntax failure, printed with empty stderr - it read Syntax-checked 364 files: 1 failed on an unmodified tree and passed on an immediate re-run.

`docs/FORGE_TROUBLESHOOTING.md` told a reader that the volume was full and what four symptoms it produces. It never said how to find *what* filled it, which is the measurement that took #1507 four days: `GET /api/v1/repos/search?sort=size` returned 46.2 GiB in one private repository against 0.0 GiB in this one (96% of the instance). The added section also carries the distinction that decides what reclaims it: stored size is not tree size. `packetforge-firmware` holds 46.2 GiB against a tip of 6.4 MB across 396 blobs, one branch and no tags - so the dumps are previous commits, and `git gc` (and every `204`-answering housekeeping task) could never have freed them. `count-objects -vH` against `ls-tree -r -l HEAD` is the two-command split. Every command in the section was run before it was written down, in the shell that prints it. The ways out - history rewrite, moving the repository off the volume, deleting it - are decisions about content, so they stay with #1507 and this does not close it. **Tests:** new `test/forge-space-accounting.test.js`, 10 assertions; 10 failed against the previous page and 10 pass against this one, so the section cannot be deleted back to a `df -h` page. `scripts/syntax-check.js` 365 files all OK, `check-control-bytes` clean, `check-canonical-urls` 2979 files OK, `run-tests --filter=doc` 5 suites / 126 assertions, `--filter=canonical` 52 assertions, all green. No engine code touched. Found while running the gates, not fixed here (one issue per run): a `node --check` child that fails to *start* on this Windows host (`0xC0000142`, STATUS_DLL_INIT_FAILED under load) is counted by `scripts/syntax-check.js` as a syntax failure, printed with empty stderr - it read `Syntax-checked 364 files: 1 failed` on an unmodified tree and passed on an immediate re-run.
docs(troubleshooting): the disk-full page says which repository owns the space (#1507)
All checks were successful
CI / Classify the change (pull_request) Successful in 15s
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 15s
CI / Server smoke test (pull_request) Successful in 15s
CI / Test (Node 20) (pull_request) Successful in 56s
CI / Docker build (pull_request) Successful in 30s
CI / Test (Node 18) (pull_request) Successful in 1m1s
CI / Test (Node 22) (pull_request) Successful in 1m1s
CI / Arm auto-merge (pull_request) Successful in 12s
f42d1c3d9c
`df -h` says the volume is full and nothing on that page said what filled it, which is
why #1507 was read as four unrelated failures for four days. The API ranks repositories by
size on disk; on 2026-11-12 that one query returned 46.2 GiB in a single private repository
against 0.0 GiB in this one - 96% of the instance.

The second half is the distinction that decides what reclaims it: stored size is not tree
size. `packetforge-firmware` holds 46.2 GiB against a tip of 6.4 MB across 396 blobs, one
branch, no tags - history, not a working tree - which is why `git_gc_repos`, `repo_health_check`
and the rest all answered `204` and freed nothing. `git gc` cannot collect a reachable object.

The ways out (history rewrite, move, delete) stay decisions about content and are left to
#1507; the page now makes the measurement, and the reason the usual cleanup cannot help,
reachable from inside the repository.

test/forge-space-accounting.test.js locks the section: 10 assertions, all failing on the
previous page and all passing on this one.

Co-authored-by: Hermes Agent <jay@jayw.uk>
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!1744
No description provided.