How to Overlay two files with UnionFs in a Linux System

Overlaying filesystems is a powerful way to combine multiple directories into a single unified view. Whether you’re managing container layers, working on backups, or building isolated environments, UnionFS (Union File System) can simplify your workflow.

In this post, we’ll break down how to overlay two directories using UnionFS on a Linux system. We’ll skip the fluff and get straight to the steps.

What Is UnionFS?

UnionFS is a stackable unification file system. It allows you to “merge” multiple directories (branches) into a single virtual directory. From the user’s perspective, everything looks like it’s in one place.

The key concept: UnionFS overlays one directory on top of another. You can define which one takes priority (i.e., where files are written).

Why Use UnionFS?

• Layer file changes without touching the original.
• Test software or configs in a temporary layer.
• Combine read-only and writable sources into a unified space.

Step-by-Step: Overlay Two Directories with UnionFS

1. Install UnionFS-FUSE

UnionFS is often used via FUSE (Filesystem in Userspace), so first install it:

Debian/Ubuntu:

sudo apt update
sudo apt install unionfs-fuse

RHEL/CentOS:

sudo yum install fuse-sshfs

If unionfs-fuse isn’t in your default repo, you might need to build it from source or use an alternative like OverlayFS.

2. Prepare Your Directories

Let’s say you have:

• /home/user/base — your original files
• /home/user/overlay — new changes
• /home/user/union — the merged view

Make sure they exist:

mkdir -p /home/user/base /home/user/overlay /home/user/union

Add a test file to the base:

echo "This is the base layer" > /home/user/base/file.txt

3. Mount with UnionFS

Use unionfs-fuse to mount the directories:

unionfs-fuse -o cow /home/user/overlay=RW:/home/user/base=RO /home/user/union

Explanation:

• cow = copy-on-write mode
• RW = read/write layer
• RO = read-only layer
• /home/user/union = mount point

Now, when you look inside /home/user/union, you’ll see the contents of both layers, with overlay files taking precedence.

4. Test It

Read the merged file:

cat /home/user/union/file.txt

Now try editing or creating a new file in the union directory:

echo "Modified in overlay" > /home/user/union/file.txt
echo "Overlay-only file" > /home/user/union/new.txt

Check where the changes went:

cat /home/user/overlay/file.txt
cat /home/user/overlay/new.txt

The original base is untouched.

5. Unmount When Done

To unmount:

fusermount -u /home/user/union

Final Notes

UnionFS is a smart way to test changes or combine file sources without making permanent modifications. It’s especially useful for developers, system admins, and anyone working with layered environments.

For more robust and performance-optimized setups, also explore OverlayFS, which is natively supported in modern Linux kernels.

Got questions or want help scripting this? Drop a comment below or reach out through the contact page.