Per-repo documentation — each repo's docs/ and README, ingested and associated with the repo. Rendered through the <<<RepoDocs>>> tag.
← diskforge docs · README.md
A from-scratch, usermode disk-image toolkit: it writes ext4 / FAT32 / exFAT filesystems and composes them into MBR/GPT disks, and it reads qcow2/raw images — walking a guest filesystem into per-file members — without mkfs, mount, loopback, qemu-nbd, or root. Pure Python standard library; runs on a macOS host.
It is the engine behind two consumers: - omni-git — _add_image ingests a disk image additively: the whole image is still stored byte-for-byte as one content-addressed blob, and in addition diskforge walks the guest filesystem so each guest file is content-addressed and deduped into the store. - pi-img — pi_img_diskforge.py exposes list_files() / extract_files() over a real guest filesystem via the diskforge reader.
- Selftest: 63/63 green (python3 selftest.py), kernel-judged. - Provenance: registered in the forge (config/forge/remotes/diskforge.git) and mirrored to GitLab testmonkeyalpha-group/jazz-forge/diskforge (private). Tracked by congruency ticket #495.
Building filesystem fixtures and reading guest files normally needs root and kernel machinery (mount, loopback, qemu-nbd). diskforge does both in userspace so it can run unprivileged on a dev host and inside sandboxes. Its writer is never graded by its own reader — a real Linux kernel (e2fsck/debugfs/mount in a Docker Sandbox, via diskforge.judge) is the independent oracle.
- diskforge/ext4/, diskforge/fat/, diskforge/exfat/ — from-scratch filesystem writers (byte-reproducible: pinned UUIDs/timestamps/layout). - diskforge/disk/ — MBR/GPT disk composition (compose.py, gpt.py). - diskforge/reader/ — usermode readers: partition, ext4, fat32, exfat, qcow2, plus importer/image/source/entry (walk a guest fs → member stream). - diskforge/sink/ — output sinks: paxtar (pax TAR) and omnigit (content-addressed store). - diskforge/wire/ — integration surface for consumers (see Public API). - diskforge/judge.py — kernel/e2fsprogs validation harness (the independent oracle). - diskforge/fixtures.py, selftest.py — deterministic fixtures + the acceptance suite.
The stable integration entry point that consumers import is the wire module:
from diskforge.wire import index_image_members, MemberIndexError
- index_image_members(image_path, ...) — walk a disk image's guest filesystem and yield a per-file member index (path, bytes/blob, hardlink sets) for content-addressed dedup. - MemberIndexError — raised when an image has no walkable guest filesystem (e.g. a synthetic fixture). Consumers degrade to stock behavior on ImportError (diskforge absent) or MemberIndexError, so wiring diskforge in is always additive.
Pure Python standard library — no pip dependencies. Consumers activate it by placing the repo root on PYTHONPATH (e.g. the omni-git launcher shim adds ~/code/diskforge), so import diskforge.wire resolves (diskforge/diskforge/wire/).
The kernel-judged selftest additionally needs the diskforge Docker Sandbox (sbx) that diskforge.judge drives; the writer/reader themselves need nothing beyond stdlib.
cd ~/code/diskforge && python3 selftest.py # 63/63; each pin has a RED negative control
Every check is a pin: a positive that must pass and a negative control (an old or deliberately-broken implementation, kept verbatim) proven to go red. The kernel is the judge for all writer output.
Identity is content-addressed: guest files and whole images are keyed by sha256 and folded into the content-addressed store (aligning with the bakery discipline, RFC-0009: sha256 is authoritative identity). diskforge produces the member stream; the sink (omnigit) records and dedups it.