Unionfs is a stackable unification file system, which can appear to merge
the contents of several directories (branches), while keeping their physical
content separate.  Unionfs is useful for unified source tree management,
merged contents of split CD-ROM, merged separate software package
directories, data grids, and more.  Unionfs allows any mix of read-only and
read-write branches, as well as insertion and deletion of branches anywhere
in the fan-out.  To maintain Unix semantics, Unionfs handles elimination of
duplicates, partial-error conditions, and more.

# mount -t unionfs -o branch-option[,union-options[,...]] none MOUNTPOINT

The available branch-option for the mount command is:

	dirs=branch[=ro|=rw][:...]

specifies a separated list of which directories compose the union.
Directories that come earlier in the list have a higher precedence than
those which come later. Additionally, read-only or read-write permissions of
the branch can be specified by appending =ro or =rw (default) to each
directory.

Syntax:

	dirs=/branch1[=ro|=rw]:/branch2[=ro|=rw]:...:/branchN[=ro|=rw]

Example:

	dirs=/writable_branch=rw:/read-only_branch=ro


DYNAMIC BRANCH MANAGEMENT AND REMOUNTS
======================================

You can remount a union and change its overall mode, or reconfigure the
branches, as follows.

To downgrade a union from read-write to read-only:

# mount -t unionfs -o remount,ro none MOUNTPOINT

To upgrade a union from read-only to read-write:

# mount -t unionfs -o remount,rw none MOUNTPOINT

To delete a branch /foo, regardless where it is in the current union:

# mount -t unionfs -o remount,del=/foo none MOUNTPOINT

To insert (add) a branch /foo before /bar:

# mount -t unionfs -o remount,add=/bar:/foo none MOUNTPOINT

To insert (add) a branch /foo (with the "rw" mode flag) before /bar:

# mount -t unionfs -o remount,add=/bar:/foo=rw none MOUNTPOINT

To insert (add) a branch /foo (in "rw" mode) at the very beginning (i.e., a
new highest-priority branch), you can use the above syntax, or use a short
hand version as follows:

# mount -t unionfs -o remount,add=/foo none MOUNTPOINT

To append a branch to the very end (new lowest-priority branch):

# mount -t unionfs -o remount,add=:/foo none MOUNTPOINT

To append a branch to the very end (new lowest-priority branch), in
read-only mode:

# mount -t unionfs -o remount,add=:/foo=ro none MOUNTPOINT

Finally, to change the mode of one existing branch, say /foo, from read-only
to read-write, and change /bar from read-write to read-only:

# mount -t unionfs -o remount,mode=/foo=rw,mode=/bar=ro none MOUNTPOINT


CACHE CONSISTENCY
=================

If you modify any file on any of the lower branches directly, while there is
a Unionfs 2.0 mounted above any of those branches, you should tell Unionfs
to purge its caches and re-get the objects.  To do that, you have to
increment the generation number of the superblock using the following
command:

# mount -t unionfs -o remount,incgen none MOUNTPOINT

Note that the older way of incrementing the generation number using an
ioctl, is no longer supported in Unionfs 2.0.  Ioctls in general are not
encouraged.  Plus, an ioctl is per-file concept, whereas the generation
number is a per-file-system concept.  Worse, such an ioctl requires an open
file, which then has to be invalidated by the very nature of the generation
number increase (read: the old generation increase ioctl was pretty racy).


For more information, see <http://unionfs.filesystems.org/>.
