Avoid mixed groups
A real directory named (root files) used to collide with the root bucket. Directory keys now start with ./ and the report is versioned.
ENGINEERING NOTE / PYTHON TOOL
File inventory, with a clear scope.
A small Python tool for inspecting directory sizes. Define exclusions, list large files and record unreadable paths before deciding what to organize.
01 / Try the scope, see the difference
This five-file fixture is shared with the Python example. The browser recalculates this synthetic list; it does not access your disk.
- Included files
- 4
- Logical bytes
- 40
- At or above threshold
- 2
| Relative path | Bytes |
|---|---|
| assets/sample.txt | 16 |
| src/app.js | 12 |
4 files included, 40 bytes total; 2 files meet the threshold.
The totals are deliberately tiny so they can be checked by hand. They are not storage-saving or performance results.
02 / Small tool, concrete decisions
Keep reports outside the scan
A previous report must not inflate the next scan. The CLI checks the output path before scanning and refuses existing files.
Make exclusions explicit
Exact relative paths skip the selected subtree. Similar names and nested directories remain separate choices.
Report partial observations
Readable files remain in the report when a path fails; error types and completeness are visible beside the totals.
03 / Run and verify
Python 3.10+ and the standard library. Start with the synthetic example, then choose your own directory and an existing output folder outside it.
python examples/make_sample.py
python -m unittest discover -s tests -v
python scripts/inventory.py --root "D:\ExampleProject" --output "D:\Reports\inventory.json" --exclude node_modules --large-mib 32Local run: 14 of 15 tests passed; the real-symlink check was skipped because this host cannot create symlinks. Windows / Ubuntu CI for Python 3.10 and 3.12 completed successfully. Inspect the logs for each job’s pass and skip counts.
04 / What the numbers mean
Logical length is not allocated disk space. Hardlinks count per path, exclusions are omitted, and a changing filesystem is not an atomic snapshot. Reports may contain private names and should be reviewed before sharing.