-W flag is an option that most users of
BSD/OSX will never need to use, as it only applies to "union mounts". This type of mount simply allows several filesystems to be mounted, appearing as just one filesystem. To explain this further, here's the abstract from a paper, titled "Union Mounts in 4.4BSD-Lite", by the authors, Jan-Simon Pendry and Marshall Kirk McKusick:
Unlike a traditional mount that hides the contents of the directory on which it
is placed, a union mount presents a view of a merger of the two directories.
Although only the filesystem at the top of the union stack can be modified, the
union filesystem gives the appearance of allowing anything to be deleted or
modified. Files in the lower layer may be deleted with whiteout in the top layer.
Files to be modified are automatically copied to the top layer. This new
functionality makes possible several new applications including the ability to
apply patches to a CD-ROM and eliminate symbolic links generated by an
automounter. Also possible is the provision of per-user views of the filesystem,
allowing private views of a shared work area, or local builds from a centrally
shared read-only source tree.
This paper also discusses whiteout operations:
If a name is being removed from the lower layer's namespace a whiteout is
created in the upper layer. A whiteout has the effect of masking out the name in
the lower layer. Operations that cause a whiteout to be created include unlink,
rmdir and rename.
Putting it altogether,
rm with the
-W flag uses the "whiteout" created in the top layer to restore the files "deleted" from the lower layer. For usage, please see the manual.