rootfs-diff compares two embedded Linux root filesystem (rootfs) archives and shows what changed between releases. Use it as a command-line tool or a Go library.
Supply complete tar or tar.gz archives from Buildroot, Yocto or any build system that produces a supported archive. rootfs-diff reads the file contents and metadata stored in each archive without extracting files or running their contents. It writes text, JSON or Markdown reports. The same logical inputs and options produce identical report bytes.
Reports show added, removed and modified paths, including changes to content hashes, numeric ownership, permissions, link targets and device metadata. To make a change fail CI, enable a check: require specific paths, set a limit on net file-content growth, or fail on any change. By default, finding differences is a successful comparison.
The Buildroot example was run against two archives generated by Buildroot. Every archive entry was also inspected independently to check the report. Follow the recipe and reproduction commands to repeat the comparison with the same Buildroot version.
The command reported these controlled changes. Paths are relative to the root filesystem, so etc/device.conf refers to /etc/device.conf on the target device.
| Recorded path | Controlled change |
|---|---|
etc/init.d/S40network |
Removed |
etc/device.conf |
Mode 0640 to 0666 |
usr/bin/device-agent |
Symlink target agent-v1 to agent-v2 |
usr/lib/libexample.so |
Grows by 420 KiB (430,080 bytes) |
The report contains one removal, three modifications, no additions and no metadata warnings. The 430,080-byte file increase minus the removed 17-byte startup script gives 430,063 bytes of net growth. This measures uncompressed regular-file contents, not flash usage or download size.
The images contain files created for the demonstration: S40network and the agent endpoints are stubs, and libexample.so is a fully written file filled with zero bytes. The demonstration does not run the files or boot either image.
To make CI fail when the startup script is missing, save the following policy as required-paths.json. It checks only that the path is present; it sets no growth limit. Policy paths use the same root-relative spelling as report paths:
{
"schema_version": 1,
"required_paths": ["etc/init.d/S40network"]
}./bin/rootfs-diff --policy required-paths.json before.tar after.tarFor the Buildroot archive pair, this command exits with code 1, writes a complete report and lists one required_path violation. The full example also sets a 409,600-byte net growth limit, so its report lists two violations. Without an enabled check, differences return exit code 0. Invalid input or an operational failure returns exit code 2, and the output may be incomplete. See the CI example for handling these exit codes.
Download v0.1.2 binaries and checksums, or build from source with Go 1.27.4. The module requires at least Go 1.27.0. Linux and macOS are supported on amd64 and arm64. Choose the binary for the computer running rootfs-diff, regardless of the firmware's CPU architecture. See the installation guide for binary, source and Go module setup.
git clone https://github.com/Azhovan/rootfs-diff.git
cd rootfs-diff
./scripts/verify.shBuild the command, then compare your baseline and candidate rootfs archives:
go build -o ./bin/rootfs-diff ./cmd/rootfs-diff
./bin/rootfs-diff baseline.tar candidate.tar.gz
./bin/rootfs-diff --format json baseline.tar candidate.tar.gz > report.json
./bin/rootfs-diff --policy policy.json baseline.tar candidate.tar.gzFor the last command, save the sample policy as policy.json and adapt it to your candidate archive. To try the library without supplying archive files, run the self-contained example:
go run ./examples/libraryPut all flags before the two filenames. Exit code 0 means the comparison and all enabled checks passed. Code 1 means a check failed, with a complete report explaining the result. Code 2 means invalid input or an operational failure; treat any output as incomplete.
- Installation, module access and private copies
- CLI flags, policies, ignores and exits
- Archive metadata, paths, links, growth and limits
- Go library API and ownership, example structure
- Report formats and compatibility, model fields, JSON schema
- GitHub Actions usage, troubleshooting
- Contributor setup and local checks
Start with the synthetic example for a small comparison you can reproduce locally. The Buildroot demonstration describes the two-image comparison above, including its prerequisites, controlled changes and observed report.
v0.1 reads local tar and tar.gz files and compares the contents and metadata recorded in them. It excludes timestamps, user and group names, extended attributes (xattrs), access control lists (ACLs), file capabilities and SELinux labels. Every report lists the excluded metadata. Encountered xattrs, ACLs, capabilities, SELinux labels and unrecognized vendor PAX metadata also produce warnings; timestamps and user or group names do not. Sparse archives and unsupported input formats fail. See semantics and limits.
An archive comparison cannot establish whether firmware boots, runs correctly, supports an over-the-air (OTA) update, is affected by a CVE, meets compliance requirements or is secure. rootfs-diff does not unpack raw firmware, mount filesystems, identify the packages that own files or run target binaries.
Yocto buildhistory records package and image information, including file permissions, ownership, sizes and symlinks. rootfs-diff can provide a similar file-level review from standalone tar archives produced by different build systems, with checks you choose explicitly. If you use buildhistory, keep its package, dependency and build context alongside the archive report. diffoscope provides broader artifact comparisons.
The import path is github.com/Azhovan/rootfs-diff, package rootfsdiff. Development follows the v0.1 contract and delivery issue.
rootfs-diff is licensed under the Apache License, Version 2.0 (Apache-2.0). Third-party components, including Go and Buildroot, retain their own licenses and notices.