macOS rm command '-W' option – undelete

I was looking at the man page for the rm command on my MacBook and I noticed the the following:

-W Attempt to undelete the named files. Currently, this option can only be used to recover
files covered by whiteouts.

What does this mean? What is a “whiteout”?

Asked By: user14755


A “whiteout” is a feature of some union filesystem.

If you have a file hierarchy that is overlain by a union mount, and a file exists in both layers of the resulting visible file hierarchy, a “whiteout” may be used to remove the file from the top layer while preserving it in the lower layer (like using Tipp-ex).

The rm utility is able to remove the whiteout and make the file appear again (since it was never deleted from the lower file system).

Answered By: Kusalananda

A whiteout is a special marker file placed by some “see-through” higher-order filesystems (those which use one or more real locations as a basis for their presentation), particularly union filesystems, to indicate that a file that exists in one of the base locations has been deleted within the artificial filesystem even though it still exists elsewhere. Listing the union filesystem won’t show the whited-out file.

Having a special kind of file representing these is in the BSD tradition that macOS derives from: macOS uses st_mode bits 0160000 to mark them. Using ls -F, those files will be marked with a % sign, and ls -W will show that they exist (otherwise, they’re generally omitted from listings). Many union systems also make normal files with a special name to represent whiteouts on systems that don’t support those files.

I’m not sure that macOS exposes these itself in any way, but other systems from its BSD heritage do and it’s possible that external filesystem drivers could use them.

Answered By: Michael Homer
Categories: Answers Tags: , , ,
Answers are sorted by their score. The answer accepted by the question owner as the best is marked with
at the top-right corner.