Itemised
Itemised is a command wrapper: type itemised in front of any command, the command runs exactly as it would have (its own output, colours, prompts, signals and exit code), and afterwards a 48 column till receipt goes to stderr listing every file the command created, changed and removed in the working directory, with exact byte totals, the exit code, the elapsed time, the free space on the volume before and after, and a plain list of what it did not look at, ending in the net as Amount due when the command used space or Change due when it gave space back. It needs Python 3.11 or later and nothing else: from this folder, uv run itemised.py bun run build (or ./itemised.py ..., whose shebang is uv run --script; put a symlink named itemised on your PATH to type it as itemised ...). Its real input is your own working directory and whatever command you give it: the real clock, lstat of real files, and the real free space of the volume. No sample data ships with it.
Usage
itemised [--also PATH]... [--full] [--limit N] [--] COMMAND [ARGS...]
--also PATHwatches one more directory; its files are printed with absolute paths (home as~). A path that does not exist stops with exit 2 before anything runs.--fullprints every file instead of grouping a directory with more than 20 items of one kind into onedir/ x Nline. Totals and the receipt number do not change.--limit Nis the entry budget for each top-level directory (default 250,000). A directory over it is dropped from both snapshots and named in the notes.--ends the options, for a command whose name starts with-.-hor--helpprints the usage line.
A shell string is itemised sh -c '...'. A command that cannot be started prints one line (itemised: not found: NAME) and exits 127 with no receipt. Ctrl-C reaches the command as usual; the receipt still prints and the exit is 130. The receipt is on cream paper (#FCF0DD, ink #1A1A1A) only when stderr is a terminal, NO_COLOR is unset and COLORTERM is truecolor or 24bit; otherwise it is plain text with no escape bytes.
A real receipt
From the acceptance run on the Linux build box, itemised wrapped around this folder's own test suite, in a fresh copy under the system temp directory. An independent find and stat sum of the tree before and after gave 29,989 and 87,321 bytes: a difference of 57,332, the net line to the byte.
itemised
normal is dead
================================================
2026-10-13 14:33:26 No. DC6FC832
Served by: uv
uv run python -m unittest -q
in /tmp/tmp.iFeDhxUdiY/c10/itemised
================================================
CREATED
__pycache__/itemised.cpython-312.pyc +34.5 kB
__pycache__/test_itemised.cpython-312.pyc
+22.8 kB
================================================
created 2 files +57,332 B
changed 0 files 0 B
removed 0 files 0 B
net +57,332 B
exit 0 1.6 s counting 0.0 s
volume free 95.15 GB before, 95.14 GB after
================================================
Not examined: made and removed during the run
Not examined: file contents, only size and times
Not examined: outside the working directory
================================================
Amount due 57.3 kB
What it does not see
- Files made and removed during the run. Only the before and after states are compared.
- File contents. A file counts as changed when its size, mtime, ctime or mode differs; a rewrite with identical bytes is a change.
- Anything outside the working directory and the
--alsopaths: global caches, home dotfolders, temp, other processes. The volume line catches what it can: when free space moved by 16 MiB or more than the receipt explains, it printsNot itemised: ... more used than itemised(orless used) and does not guess why. .gitdirectories, which are never entered and are named underSkipped:. Gitignore is not read, so ignored build output is listed.- Empty directories, hard links and clones as such. Sizes are file lengths.
- Windows. This build was tested on Linux only; macOS is in scope but was not run here.
Measured: bun install, then rm -rf node_modules
In a throwaway project under the system temp directory with a real bun.lock for vite and typescript and a populated bun cache (bun 1.4.3, run with --offline):
itemised bun install --offline:node_modules/ x 1,364under CREATED, net+92,664,943 B, which a separatefindandstatsum matched to the byte.find node_modules | wc -lcounts 1,483 entries, far under the 250,000 default, so the default stays.itemised rm -rf node_modules:node_modules/ x 1,364under REMOVED, net-92,664,943 B, matched to the byte, ending inChange due 92.7 MB.countingprinted0.0 son both receipts.Not itemisedappeared on both:90.6 MB less used than itemisedafter the install,92.2 MB more used than itemisedafter the removal. On Linux bun hard links package files from its cache, so the volume barely moves either way. The receipt states the difference; it does not name the cause.
Checks
uv run python -m unittest -q
bash acceptance.sh > out/acceptance.txt
uv run python shots.py
test_itemised.py covers the pure parts and a few real runs. acceptance.sh runs acceptance checks 2 to 11 of CARD.md for real in throwaway directories (it needs Linux with GNU tools, tmux, git and a warm bun cache) and leaves the real tmux captures in out/; shots.py turns those captures into the pages photographed in shots/. BUILD.md records each check and its output.
Colophon
Itemised, catalogue number 23 of 100. One file of Python standard library. Set in the terminal's own monospace on paper the terminal does not have, 48 columns, one ink. Every figure was measured at the counter. All amounts are in bytes. Keep this slip for your records, or do not.
Files
- README.md
- acceptance.sh
- itemised.py
- out/acceptance.txt
- out/empty-desk.html
- out/empty-phone.html
- out/install-desk.html
- out/install-phone.html
- out/pane-empty-desk.ans
- out/pane-empty-phone.ans
- out/pane-install-desk.ans
- out/pane-install-desk.txt
- out/pane-install-phone.ans
- out/pane-remove-desk.ans
- out/pane-remove-desk.txt
- out/pane-remove-phone.ans
- out/receipt-unittest.txt
- out/remove-desk.html
- out/remove-phone.html
- shots.py
- test_itemised.py