a featureful union filesystem https://trapexit.github.io/mergerfs/
Find a file
Antonio S. Musumeci 9d12bcf235 Return ENOENT, not EBADF, for removed nodes with no open file
Once a file or directory is removed (unlink, rmdir, rename over it)
libfuse has no path for its node and falls back to the fh based
getattr/setattr/statx with fh=0. If mergerfs had no open file for the
node (a directory, an O_PATH fd, a cwd, or a dentry resolved just
before the removal) it returned EBADF. The kernel sends GETATTR for
such nodes in the permission checks of a path walk, so lstat() of a
directory, or of a path below it, could fail with EBADF while rm -rf
removed it. Two rm -rf at once, one on a directory and one on the
directory above it, met it when one removed a directory the other
still had open: the other's unlinkat() through its dirfd failed, rm
reported "Bad file descriptor" and left entries behind.

mergerfs now returns ENOENT. That is what a local filesystem gives
*at() calls in a removed directory, and what rm -f ignores. ESTALE
would make the kernel redo a path based lookup, which helps a stat
racing a rename over the path. But a call through a dirfd or cwd of a
removed directory meets the same node again and fails anyway, and the
concurrent rm -rf still did. Calls on the removed object itself, which
succeed on a local filesystem, get ENOENT instead of EBADF.

TEST_rm_rf_concurrent runs the two cases reported. The rm -rf one is
a narrow race; TEST_use_dirfd_after_rmdir covers its cause without
one, with cache.attr=0 so the kernel sends GETATTR every time.

See #1693.
2026-11-17 12:25:50 -06:00
.github Remove mkdocs build github workflow 2026-04-19 23:48:13 -05:00
buildtools Fix release builds and drop Debian 11 targets 2026-11-05 15:02:42 -06:00
debian Fix release builds and drop Debian 11 targets 2026-11-05 15:02:42 -06:00
man Fix manpage links for 2.41.0-rc3 (#1555) 2025-10-29 12:07:49 -05:00
mkdocs Fix branch snapshot lifetime in EXDEV link fallback 2026-11-06 12:10:05 -06:00
src Return ENOENT, not EBADF, for removed nodes with no open file 2026-11-17 12:25:50 -06:00
tests Return ENOENT, not EBADF, for removed nodes with no open file 2026-11-17 12:25:50 -06:00
tools tools/preload: include correct extended attribute headers on FreeBSD (#1590) 2025-11-25 12:09:41 -06:00
vendored Return ENOENT, not EBADF, for removed nodes with no open file 2026-11-17 12:25:50 -06:00
.gitignore Build improvements (#1501) 2025-08-04 23:39:52 -05:00
DEPENDENCIES Fix ARMv5 atomic loads from Boost dummy storage 2026-11-14 18:27:14 -06:00
LICENSE Update copyright headers 2026-03-02 01:09:16 -05:00
Makefile Pass annobin override to RPM toolset builds 2026-05-13 17:01:41 -04:00
mergerfs.spec Build improvements (#1501) 2025-08-04 23:39:52 -05:00
README.md Fix some links in docs (#1582) 2025-11-18 08:35:27 -06:00

mergerfs - a featureful union filesystem

mergerfs is a FUSE based union filesystem geared towards simplifying storage and management of files across numerous commodity storage devices. It is similar to mhddfs, unionfs, aufs, DrivePool, etc.

Features

  • Logically combine numerous filesystems/paths into a single mount point (JBOFS: Just a Bunch of FileSystems)
  • Combine paths of the same or different filesystems
  • Ability to add or remove filesystems/paths without impacting the rest of the data
  • Unaffected by individual filesystem failure
  • Configurable file selection and creation placement
  • File IO passthrough for near native IO performance (where supported)
  • Works with filesystems of any size
  • Works with filesystems of almost any type
  • Ignore read-only filesystems when creating files
  • Hard links
  • Hard link copy-on-write / CoW
  • Runtime configurable
  • Support for extended attributes (xattrs)
  • Support for file attributes (chattr)
  • Support for POSIX ACLs

Non-features

  • Read/write overlay on top of read-only filesystem like OverlayFS
  • File whiteout
  • RAID like parity calculation (see SnapRAID)
  • Redundancy
  • Splitting of files across branches

How it works

mergerfs logically merges multiple filesystem paths together. Not block devices, not filesystem mounts, just paths. It acts as a proxy to the underlying filesystem paths. Combining the behaviors of some functions and being a selector for others.

When the contents of a directory are requested mergerfs combines the list of files from each directory, deduplicating entries, and returns that list.

When a file or directory is created a policy is first run to determine which branch will be selected for the creation.

For functions which change attributes or remove the file the behavior may be applied to all instances found.

The way in which mergerfs behaves is controlled by the config/options/settings. More specifically by policies.

Visualization

A         +      B        =       C
/disk1           /disk2           /merged
|                |                |
+-- /dir1        +-- /dir1        +-- /dir1
|   |            |   |            |   |
|   +-- file1    |   |            |   +-- file1
|                |   +-- file2    |   +-- file2
|                |   +-- file3    |   +-- file3
|                |                |
+-- /dir2        |                +-- /dir2
|   |            |                |   |
|   +-- file4    |                |   +-- file4
|                |                |
|                +-- /dir3        +-- /dir3
|                |   |            |   |
|                |   +-- file5    |   +-- file5
|                |                |
+-- file6        |                +-- file6
+-- file7        +-- file7        +-- file7

QuickStart

https://trapexit.github.io/mergerfs/latest/quickstart/

Documentation

https://trapexit.github.io/mergerfs

Support

https://trapexit.github.io/mergerfs/latest/support/

Sponsorship and Donations

https://github.com/trapexit/support

Development and support of a project like mergerfs requires a significant amount of time and effort. The software is released under the very liberal ISC license and is therefore free to use for personal or commercial uses.

If you are a non-commercial user and find mergerfs and its support valuable and would like to support the project financially it would be very much appreciated.

If you are using mergerfs commercially please consider sponsoring the project to ensure it continues to be maintained and receive updates. If custom features are needed feel free to contact me directly.