[PATCH 3/3] README: comprehensive refactor for clarity and professionalism
Saksham
aghi.saksham5 at gmail.com
Mon Mar 30 16:21:37 AEDT 2026
The current README contained several instances of awkward phrasing and
technical descriptions that could be improved for better readability
and professional presentation. Specifically, the phrase "form a generic
read-only filesystem solution" in the overview section was identified
as particularly unclear and has been refined for better flow.
This commit performs a comprehensive overhaul of the README file to:
1. Improve the introduction: Rephrased the EROFS overview to clearly
state its design goals and advantages over traditional read-only
filesystems, emphasizing the balance between efficient compression
and superior data access speeds.
2. Polish use case descriptions: Updated the list of typical scenarios
(firmware, container images, Live CDs, etc.) for better flow and
clarity. These descriptions now highlight the specific benefits
EROFS brings to each scenario, such as reduced metadata overhead
and optimized startup times.
3. Clarify tool descriptions: Standardized and improved the summaries
for mkfs.erofs, mount.erofs, erofsfuse, dump.erofs, and fsck.erofs
to ensure users understand the primary purpose of each utility in
the erofs-utils suite.
4. Enhance technical instructional sections: Refined the "How to
generate" sections to be more instructional and professional.
Algorithm lists, command examples, and technical notes on
reproducibility and pcluster management have been rewritten for
improved clarity.
5. Refine the "Comments" section: Clarified the description of
tail-packing to better explain its benefits regarding I/O
minimization and storage efficiency by eliminating internal
fragmentation in the last block of a file.
6. General copy-editing: Fixed minor grammatical issues, improved
sentence structure, and ensured consistent capitalization and
terminology throughout the document.
These changes collectively provide a more professional and informative
first impression for new users while offering clearer technical context
for developers working with EROFS. This documentation update ensures
that the README remains an effective and high-quality introduction to
the project's capabilities and tooling.
Signed-off-by: Saksham <aghi.saksham5 at gmail.com>
---
README | 298 +++++++++++++++++++++++++++------------------------------
1 file changed, 141 insertions(+), 157 deletions(-)
diff --git a/README b/README
index 6f9e761..d974305 100644
--- a/README
+++ b/README
@@ -1,292 +1,276 @@
erofs-utils
===========
-Userspace tools for EROFS filesystem, currently including:
+Userspace tools for the EROFS filesystem, including:
- mkfs.erofs filesystem formatter
- mount.erofs mount helper for EROFS
- erofsfuse FUSE daemon alternative
- dump.erofs filesystem analyzer
- fsck.erofs filesystem compatibility & consistency checker as well
- as extractor
+ mkfs.erofs Filesystem formatter
+ mount.erofs Mount helper for EROFS
+ erofsfuse FUSE-based EROFS implementation
+ dump.erofs Filesystem analyzer
+ fsck.erofs Filesystem consistency checker and extractor
-EROFS filesystem overview
+EROFS Filesystem Overview
-------------------------
-EROFS filesystem stands for Enhanced Read-Only File System. It aims to
-form a generic read-only filesystem solution for various read-only use
-cases instead of just focusing on storage space saving without
-considering any side effects of runtime performance.
+EROFS (Enhanced Read-Only File System) is designed to provide a high-performance,
+generic read-only filesystem solution for a wide variety of scenarios. Unlike
+traditional read-only filesystems that often prioritize maximum storage savings
+at the cost of significant runtime performance overhead, EROFS is engineered to
+balance efficient compression with superior data access speeds.
-Typically EROFS could be considered in the following use scenarios:
- - Firmwares in performance-sensitive systems, such as system
- partitions of Android smartphones;
+Typical EROFS use cases include:
- - Mountable immutable images such as container images for effective
- metadata & data access compared with tar, cpio or other local
- filesystems (e.g. ext4, XFS, btrfs, etc.)
+ - Firmware for performance-critical systems, such as system partitions in
+ Android smartphones;
- - FSDAX-enabled rootfs for secure containers (Linux 5.15+);
+ - Highly efficient, mountable immutable images (e.g., container images)
+ offering optimized metadata and data access compared to tar, cpio, or
+ traditional local filesystems (such as ext4, XFS, and btrfs);
- - Live CDs which need a set of files with another high-performance
- algorithm to optimize startup time; others files for archival
- purposes only are not needed;
+ - FSDAX-enabled rootfs for secure, high-performance containers (supported
+ since Linux 5.15);
- - and more.
+ - Live CDs and bootable media requiring high-performance data retrieval to
+ minimize system startup times;
-Note that all EROFS metadata is uncompressed by design, so that you
-could take EROFS as a drop-in read-only replacement of ext4, XFS,
-btrfs, etc. without any compression-based dependencies and EROFS can
-bring more effective filesystem accesses to users with reduced
-metadata.
+ - Archival storage where fast random access to compressed data is required.
-For more details of EROFS filesystem itself, please refer to:
+By design, all EROFS metadata remains uncompressed. This allows EROFS to serve
+as a high-performance, drop-in read-only replacement for filesystems like ext4,
+XFS, or btrfs, even without compression-based dependencies. This architectural
+choice ensures more effective filesystem access and reduced metadata overhead
+for end users.
+
+For more details on the EROFS filesystem itself, please refer to the official
+documentation:
https://www.kernel.org/doc/html/next/filesystems/erofs.html
-For more details on how to build erofs-utils, see `docs/INSTALL.md`.
+Detailed instructions for building erofs-utils are available in
+`docs/INSTALL.md`.
-For more details about filesystem performance, see
+For a comprehensive analysis of filesystem performance, see
`docs/PERFORMANCE.md`.
mkfs.erofs
----------
-Two main kinds of EROFS images can be generated: (un)compressed images.
+`mkfs.erofs` can generate two primary types of EROFS images: uncompressed and
+compressed.
- - For uncompressed images, there will be no compressed files in these
- images. However, an EROFS image can contain files which consist of
- various aligned data blocks and then a tail that is stored inline in
- order to compact images [1].
+ - **Uncompressed Images:** These images do not contain compressed file data.
+ However, EROFS utilizes a technique where various aligned data blocks are
+ followed by an inlined tail to compact the image size effectively [1].
- - For compressed images, it will try to use the given algorithms first
- for each regular file and see if storage space can be saved with
- compression. If not, it will fall back to an uncompressed file.
+ - **Compressed Images:** The formatter attempts to compress each regular file
+ using the specified algorithms. If compression does not yield storage
+ savings, the tool automatically falls back to an uncompressed format for
+ that specific file.
-Note that EROFS supports per-file compression configuration, proper
-configuration options need to be enabled to parse compressed files by
-the Linux kernel.
+Note that EROFS supports per-file compression configurations. Ensure that the
+target Linux kernel is configured with the necessary options to parse the
+selected compression formats.
How to generate EROFS images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Compression algorithms could be specified with the command-line option
-`-z` to build a compressed EROFS image from a local directory:
+Compression algorithms are specified using the `-z` command-line option. For
+example, to build a compressed EROFS image from a local directory using LZ4HC:
$ mkfs.erofs -zlz4hc foo.erofs.img foo/
-Supported algorithms by the Linux kernel:
+Supported algorithms in the Linux kernel:
- LZ4 (Linux 5.3+);
- LZMA (Linux 5.16+);
- DEFLATE (Linux 6.6+);
- Zstandard (Linux 6.10+).
-Alternatively, generate an uncompressed EROFS from a local directory:
+Alternatively, to generate an uncompressed EROFS image:
$ mkfs.erofs foo.erofs.img foo/
-Additionally, you can specify a higher compression level to get a
-(slightly) smaller image than the default level:
+You can also specify a higher compression level to achieve a smaller image
+size (e.g., level 12 for LZ4HC):
$ mkfs.erofs -zlz4hc,12 foo.erofs.img foo/
-Multi-threaded support can be explicitly enabled with the ./configure
-option `--enable-multithreading`; otherwise, single-threaded compression
-will be used for now. It may take more time on multiprocessor platforms
-if multi-threaded support is not enabled.
+Multi-threaded support can be enabled during the build process using the
+`--enable-multithreading` configure option. If enabled, `mkfs.erofs` will
+utilize multiple processors to accelerate the compression process.
-Currently, `-Ededupe` doesn't support multi-threading due to limited
-development resources.
+Currently, the `-Ededupe` option does not support multi-threading.
Reproducible builds
~~~~~~~~~~~~~~~~~~~
-Reproducible builds are typically used for verification and security,
-ensuring the same binaries/distributions to be reproduced in a
-deterministic way.
-
-Images generated by the same version of `mkfs.erofs` will be identical
-to previous runs if the same input is specified, and the same options
-are used.
+EROFS supports reproducible builds, which are essential for verification and
+security. This ensures that the same input and options always result in
+bit-for-bit identical filesystem images.
-Specifically, variable timestamps and filesystem UUIDs can result in
-unreproducible EROFS images. `-T` and `-U` can be used to fix them.
+To ensure reproducibility, you may need to fix variable timestamps and
+filesystem UUIDs using the `-T` and `-U` options, respectively.
How to generate EROFS big pcluster images (Linux 5.13+)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By default, EROFS formatter compresses data into separate one-block
-(e.g. 4KiB) filesystem physical clusters for outstanding random read
-performance. In other words, each EROFS filesystem block can be
-independently decompressed. However, other similar filesystems
-typically compress data into "blocks" of 128KiB or more for much smaller
-images. Users may prefer smaller images for archiving purposes, even if
-random performance is compromised with those configurations, and even
-worse when using 4KiB blocks.
-
-In order to fulfill users' needs, big pclusters has been introduced
-since Linux 5.13, in which each physical clusters will be more than one
-blocks.
-
-Specifically, `-C` is used to specify the maximum size of each pcluster
-in bytes:
+By default, the EROFS formatter compresses data into separate one-block (e.g.,
+4KiB) physical clusters (pclusters) to ensure exceptional random read
+performance. This allows each block to be decompressed independently. In
+contrast, other filesystems often use much larger compression blocks (128KiB+),
+which can improve compression ratios at the expense of random access latency.
+
+To accommodate different needs, "big pclusters" were introduced in Linux 5.13,
+allowing physical clusters to span multiple blocks.
+
+The `-C` option specifies the maximum pcluster size in bytes:
$ mkfs.erofs -zlz4hc -C65536 foo.erofs.img foo/
-Thus, in this case, pcluster sizes can be up to 64KiB.
+In this example, pcluster sizes can reach up to 64KiB.
-Note that large pcluster size can degrade random performance (though it
-may improve sequential read performance for typical storage devices), so
-please evaluate carefully in advance. Alternatively, you can make
-per-(sub)file compression strategies according to file access patterns
-if needed.
+Note: Larger pcluster sizes may improve sequential read performance on some
+storage devices but can degrade random access performance. Evaluate your
+workload requirements carefully. You can also apply per-file compression
+strategies based on specific access patterns.
How to generate EROFS images with multiple algorithms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It's possible to generate an EROFS image with files in different
-algorithms due to various purposes. For example, LZMA for archival
-purposes and LZ4 for runtime purposes.
+EROFS allows mixing different compression algorithms within a single image to
+suit different needs—for instance, using LZMA for archival data and LZ4 for
+frequently accessed runtime files.
-In order to use alternative algorithms, just specify two or more
-compressing configurations together separated by ':' like below:
+To use multiple algorithms, specify them in the `-z` option separated by
+colons:
-zlzma:lz4hc,12:lzma,9 -C32768
-Although mkfs still choose the first one by default, you could try to
-write a compress-hints file like below:
+While the formatter defaults to the first algorithm, you can use a
+compress-hints file to map specific files or directories to different
+algorithms:
4096 1 .*\.so$
32768 2 .*\.txt$
4096 sbin/.*$
16384 0 .*
-and specify with `--compress-hints=` so that ".so" files will use
-"lz4hc,12" compression with 4k pclusters, ".txt" files will use
-"lzma,9" compression with 32k pclusters, files under "/sbin" will use
-the default "lzma" compression with 4k pclusters and other files will
-use "lzma" compression with 16k pclusters.
+Specify the hints file with `--compress-hints=`. In this configuration, `.so`
+files use `lz4hc,12` with 4KiB pclusters, `.txt` files use `lzma,9` with 32KiB
+pclusters, and so on.
-Note that the largest pcluster size should be specified with the "-C"
-option (here 32k pcluster size), otherwise all larger pclusters will be
-limited.
+Note: The `-C` option must specify the largest pcluster size used in the
+hints file to avoid limiting compression efficiency.
How to generate well-compressed EROFS images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Even if EROFS is not designed for such purposes in the beginning, it
-could still produce some smaller images (not always) compared to other
-approaches with better performance (see `docs/PERFORMANCE.md`). In
-order to build well-compressed EROFS images, try the following options:
- -C1048576 (5.13+)
- -Eztailpacking (5.16+)
- -Efragments / -Eall-fragments ( 6.1+);
- -Ededupe ( 6.1+).
+While EROFS prioritizes performance, it can still achieve competitive
+compression ratios. To maximize storage efficiency, consider the following
+options:
+ -C1048576 (Large pclusters, Linux 5.13+)
+ -Eztailpacking (Tail-packing for compressed files, Linux 5.16+)
+ -Efragments / -Eall-fragments (Fragment-based compression, Linux 6.1+)
+ -Ededupe (Global data deduplication, Linux 6.1+)
-Also EROFS uses lz4hc level 9 by default, whereas some other approaches
-use lz4hc level 12 by default. So please explicitly specify
-`-zlz4hc,12 ` for comparison purposes.
+EROFS defaults to LZ4HC level 9. For maximum compression, specify level 12:
+ `-zlz4hc,12`
How to generate legacy EROFS images (Linux 4.19+)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Decompression inplace and compacted indexes have been introduced in
-Linux v5.3, which are not forward-compatible with older kernels.
-
-In order to generate _legacy_ EROFS images for old kernels,
-consider adding "-E legacy-compress" to the command line, e.g.
+Features like in-place decompression and compacted indexes (introduced in
+Linux 5.3) are not compatible with older kernels. To generate images for
+kernels between 4.19 and 5.3, use the legacy option:
$ mkfs.erofs -E legacy-compress -zlz4hc foo.erofs.img foo/
-For Linux kernel >= 5.3, legacy EROFS images are _NOT recommended_
-due to runtime performance loss compared with non-legacy images.
+Note: Legacy images are not recommended for Linux kernel 5.3 and newer, as
+they do not benefit from the performance optimizations available in modern
+EROFS implementations.
Obsoleted erofs.mkfs
~~~~~~~~~~~~~~~~~~~~
-There is an original erofs.mkfs version developed by Li Guifu,
-which was replaced by the new erofs-utils implementation.
-
+The original `erofs.mkfs` implementation by Li Guifu has been superseded by
+the current `erofs-utils`. The old version is available for historical
+reference but is highly discouraged for production use:
git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git -b obsoleted_mkfs
-PLEASE NOTE: This version is highly _NOT recommended_ now.
-
mount.erofs
-----------
-mount.erofs is a mount helper for EROFS filesystem, which can be used
-to mount EROFS images with various backends including direct kernel
-mount, FUSE-based mount, and NBD for remote sources like OCI images.
+`mount.erofs` is a versatile mount helper that supports various backends,
+including direct kernel mounts, FUSE-based mounts, and NBD for remote
+sources like OCI images.
How to mount an EROFS image
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To mount an EROFS image directly:
+Direct kernel mount:
$ mount.erofs foo.erofs /mnt
-To mount with FUSE backend:
+FUSE-based mount:
$ mount.erofs -t erofs.fuse foo.erofs /mnt
-To mount from OCI image with NBD backend:
+NBD-based mount from an OCI image:
$ mount.erofs -t erofs.nbd -o oci.blob=sha256:... <IMAGE>:<TAG> mnt
-To unmount an EROFS filesystem:
+Unmount:
$ mount.erofs -u mnt
-For more details, see mount.erofs(8) manpage.
+Refer to the `mount.erofs(8)` manpage for further details.
erofsfuse
---------
-erofsfuse is introduced to support EROFS format for various platforms
-(including older linux kernels) and new on-disk features iteration.
-It can also be used as an unpacking tool for unprivileged users.
-
-It supports fixed-sized output decompression *without* any in-place
-I/O or in-place decompression optimization. Also like the other FUSE
-implementations, it suffers from most common performance issues (e.g.
-significant I/O overhead, double caching, etc.)
+`erofsfuse` provides EROFS support for platforms without native kernel
+drivers and serves as a tool for rapid feature iteration. It is also
+useful for unprivileged users to unpack EROFS images.
-Therefore, NEVER use it if performance is the top concern.
+`erofsfuse` performs fixed-sized output decompression and does not include
+the in-place I/O or decompression optimizations found in the kernel driver.
+As with most FUSE implementations, it may experience higher I/O overhead
+and double caching. It is not recommended for performance-critical
+applications.
How to mount an EROFS image with erofsfuse
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-As the other FUSE implementations, it's quite easy to mount by using
-erofsfuse, e.g.:
+To mount an image:
$ erofsfuse foo.erofs.img foo/
-Alternatively, to make it run in foreground (with debugging level 3):
+To run in the foreground with debug logging (level 3):
$ erofsfuse -f --dbglevel=3 foo.erofs.img foo/
-To debug erofsfuse (also automatically run in foreground):
+To run in debug mode (automatically foreground):
$ erofsfuse -d foo.erofs.img foo/
-To unmount an erofsfuse mountpoint as a non-root user:
+To unmount as a non-root user:
$ fusermount -u foo/
dump.erofs and fsck.erofs
-------------------------
-dump.erofs and fsck.erofs are used to analyze, check, and extract
-EROFS filesystems. Note that extended attributes and ACLs are still
-unsupported when extracting images with fsck.erofs.
+`dump.erofs` and `fsck.erofs` are essential tools for analyzing, verifying,
+and extracting EROFS filesystems. Note that extended attributes (xattrs) and
+ACLs are currently not supported during extraction with `fsck.erofs`.
+
+Extraction in `fsck.erofs` is currently single-threaded. Contributions to
+optimize this process are welcome.
-Note that extraction with fsck.erofs is still single-threaded and will
-need optimization later. If you are interested, contributions are, as
-always, welcome.
Contribution
------------
-erofs-utils is a part of EROFS filesystem project, which is completely
-community-driven open source software. If you have interest in EROFS,
-feel free to send feedback and/or patches to:
+EROFS-utils is a key component of the EROFS filesystem project and is
+entirely community-driven. We welcome feedback, bug reports, and patches.
+
+Please send your contributions to the mailing list:
linux-erofs mailing list <linux-erofs at lists.ozlabs.org>
Comments
--------
-[1] According to the EROFS on-disk format, the tail blocks of files
- could be inlined aggressively with their metadata (called
- tail-packing) in order to minimize the extra I/Os and the storage
- space.
+[1] EROFS on-disk format allows the tail blocks of files to be inlined
+ with their metadata (tail-packing). This reduces extra I/O operations
+ and saves storage space by eliminating internal fragmentation in the
+ last block of a file.
--
2.53.0
More information about the Linux-erofs
mailing list