Turn a directory, an OCI image or another image into a valid, mountable filesystem image — ext4, squashfs, EROFS, FAT, ISO 9660 and eight more — entirely in-process.
No root, no cgo, no shelling out, no third-party dependency. Identical inputs produce byte-identical output, which is what makes an image worth signing.
go get github.com/emmanuel-deloget/fsforgeRequires Go 1.24+ · runs on Linux, macOS and Windows · fsforge help for the command
Formats
Every format here is one fsforge writes. That is the project’s rule: a format it cannot write is a format it does not ship. Most engines open an existing image as well, which is what turns them into conversion sources.
e2fsckunsquashfsfsck.erofscpioudfinfo7zgenromfsfsck.fatfsck.exfatxorrisopodmanA partition table and a QCOW2 file are not filesystems — they are what a filesystem is written into. Give mkfs, a convert sink or fsforge disk an output path ending in .qcow2 and the result is a sparse QCOW2; a QCOW2 input is decoded transparently, whichever engine reads it.
sfdiskqemu-imgThe tool named on each card is what the conformance suite hands the image to. It is used by the tests and nowhere else: at runtime the library and the command start no process at all.
Features
fsforge is a library first, with a thin command on top. Everything below follows from one decision: produce the bytes yourself, rather than drive the tool that would.
The library links no C and starts no process. Building an ext4 image is ordinary user code — which is what makes it work inside an unprivileged CI container, and on a laptop that is not running Linux.
The module imports the standard library and nothing else: go.mod carries no require block and there is no go.sum. Nothing transitive to vendor, audit or keep up to date.
Only the metadata tree lives in memory. File contents are read through an io.ReaderAt while the image is laid out, so image size is bounded by the disk rather than by RAM.
Every engine loads into, and lays out from, the same logical tree. An OCI image becomes an ext4 root, an ext4 root becomes a squashfs archive, and a host directory is simply another kind of source.
Images are mutated on disk, never live. That removes crash consistency, incremental allocation and transactional recovery in one stroke: a journal is replayed on load, and a fresh empty one is written on finalize.
fsforge disk writes a GPT with an ESP and a root partition, each formatted by whichever engine you name. Any output path ending in .qcow2 comes out as a sparse QCOW2, ready for qemu.
Flatten an OCI layout into a tree, or stack another source onto an existing image as a new layer — additively, or as a delta carrying whiteouts for what the new tree removed.
The conformance suite hands every image to the tool that owns the format — e2fsck, unsquashfs, fsck.erofs, xorriso, qemu-img — and to the kernel wherever mounting one is possible.
How it works
Creating an image and mutating one are the same pipeline, not two engines. Create starts from an empty tree; mutate parses an existing image lazily into that same tree.
A filesystem is modelled as a single tree of inodes, and each engine lays that tree out on disk its own way. Finalize is a pure function of the tree, the allocator and the environment — which is exactly what makes it deterministic.
Block IO, the clock, identifiers, allocation and compression all arrive through interfaces, so an engine can be unit-tested against fakes. What the format mandates — on-disk struct encoding, crc32c, the half_md4 htree hash — does not: hiding that behind an interface buys nothing and adds risk.
Because an image is never live while fsforge touches it, an engine may repack and defragment freely, and the hardest parts of a filesystem writer simply do not arise.
The stack
Dependencies point strictly downward, and pkg/device and pkg/tree depend on nothing else in the module — which is what keeps the graph acyclic and every engine mockable.
Reproducibility
There is no reproducible mode inside an engine. A reproducible build is one wired with a fixed clock and a fixed UUID source; the engine is identical either way, and Reproducible — or -reproducible — is that wiring choice and nothing more.
SourceDateEpoch() reads SOURCE_DATE_EPOCH for you.The counterpart is Host(), which wires the system clock and random UUIDs. Same engine, different environment — which is the whole of the difference.
$ SOURCE_DATE_EPOCH=0 fsforge mkfs -type ext4 \
-source ./rootfs -size 256M -reproducible \
-output a.img
$ SOURCE_DATE_EPOCH=0 fsforge mkfs -type ext4 \
-source ./rootfs -size 256M -reproducible \
-output b.img
$ sha256sum a.img b.img
4c8a1f…2b7e a.img
4c8a1f…2b7e b.img
Two builds of the same tree, an hour apart, on two machines. sha256sum is the entire test.
The library
The fsforge package is a facade: it wires the layers below it and holds no format logic of its own. Everything it uses is exported, so you can drop a level the moment the Builder stops fitting.
Pick a filesystem type, point it at a directory, get an image. The configuration chains, and BuildFromDir streams the contents rather than reading them in.
err := fsforge.New("ext4").
Reproducible(fsforge.SourceDateEpoch()). // SOURCE_DATE_EPOCH
Size("256M").
Label("root").
BuildFromDir("./rootfs", "root.img")
A source and a sink, each a Kind and a Path. dir, ext2, ext4, squashfs, erofs, exfat, iso, cpio, udf, cramfs, romfs and oci all serve as either, wherever the engine can load.
// An OCI image directory into an ext4 root filesystem.
err := fsforge.Convert(
fsforge.Location{Kind: "oci", Path: "./alpine-oci"},
fsforge.Location{Kind: "ext4", Path: "rootfs.img"},
fsforge.Options{Size: "256M"},
)
EngineFor selects an engine, PopulateFromDir and Graft fill an image tree, ExtractToDir writes one back out to the host, and HostDeps / ReproducibleDeps decide which clock and UUID source get wired in.
// The steps the Builder runs, wired by hand.
eng, err := fsforge.EngineFor("squashfs", fsforge.HostDeps(), 0)
img, err := eng.Format(dev, image.Params{Label: "data"})
closer, err := fsforge.PopulateFromDir(img.Root(), "./rootfs")
defer closer.Close()
err = img.Finalize()
The CLI
The fsforge command does nothing the library cannot: it parses flags and calls the facade. Four verbs cover it.
A directory in, an image out. -size is required for the fixed-size targets and ignored by the ones sized from their input.
# An ext4 image from a directory.
fsforge mkfs -type ext4 -source ./rootfs \
-output root.img -size 256M
# A squashfs archive, sized from its input and trimmed.
fsforge mkfs -type squashfs -source ./rootfs \
-output rootfs.sqfs
# Deterministic output: fixed timestamps and a zeroed UUID.
SOURCE_DATE_EPOCH=0 fsforge mkfs -type ext4 \
-source ./rootfs -output root.img \
-size 256M -reproducible
From any loadable source to any writable sink, through the shared tree. dir is a kind like the others, in both directions.
# An OCI image into a squashfs archive.
fsforge convert -from oci:./alpine-oci \
-to squashfs:rootfs.sqfs
# And back out to a host directory — no mount, no loop device.
fsforge convert -from ext4:root.img \
-to dir:./extracted
# A directory into an OCI layout, tagged.
fsforge convert -from dir:./rootfs \
-to oci:./image-oci -ref app:v1
A GPT disk carrying one or more engine-formatted partitions. A partition size is absolute, or rest for whatever is left.
# A bootable disk: an ESP in FAT32, then an ext4 root.
fsforge disk -output disk.img -size 512M \
-part esp:fat:./esp:64M \
-part root:ext4:./rootfs:rest
# The same thing as a sparse QCOW2, ready for qemu.
fsforge disk -output vm.qcow2 -size 2G \
-part root:ext4:./rootfs:rest
Stack another source onto an existing OCI image, additively or as a delta whose whiteouts record what the new tree removed.
# Add a patch directory as a new layer on app:v1.
fsforge oci-add-layer -image ./image-oci \
-ref app:v1 -from ./patch
# Or a delta against whatever the image already holds.
fsforge oci-add-layer -image ./image-oci \
-from dir:./newroot -diff
Run fsforge help for the full flag reference. Any output path ending in .qcow2 writes a QCOW2 container, whichever verb produced it.
Get started
Requires Go 1.24 or newer, and nothing else: no library to link, no tool on the PATH, no privilege to ask for.
The whole library is one import. go.sum stays empty, because there is nothing to record in it.
go get github.com/emmanuel-deloget/fsforgeOne binary, and fsforge help prints every flag it takes.
go install github.com/emmanuel-deloget/fsforge/cmd/fsforge@latestThen hand it to e2fsck -fn or mount it — which is what the conformance suite does with it.
fsforge mkfs -type ext4 -source ./rootfs -output root.img -size 256MMIT licence. Issues and pull requests welcome — CI runs the pure-Go suite on every push, and the conformance suite against the real tools.