When the -D option is given, the action of Stow is to delete a package from the target tree. Note that Stow will not delete anything it doesn’t “own”. Deleting a package does not mean removing it from the stow directory or discarding the package tree.
To delete a package, Stow recursively scans the target tree, skipping over any directory that is not included in the installation image.7 For example, if the target directory is /usr/local and the installation image for the package being deleted has only a bin directory and a man directory at the top level, then we only scan /usr/local/bin and /usr/local/man, and not /usr/local/lib or /usr/local/share, or for that matter /usr/local/stow. Any symlink it finds that points into the package being deleted is removed. Any directory that contained only symlinks to the package being deleted is removed.
After removing symlinks and empty subdirectories, any directory that contains only symlinks to a single other package is considered to be a previously “folded” tree that was “split open.” Stow will refold the tree by removing the symlinks to the surviving package, removing the directory, then linking the directory back to the surviving package. However, this behaviour can be prevented via the --no-folding option; see Invoking Stow.
This approach was introduced in version 2 of GNU Stow. Previously, the whole target tree was scanned and stow directories were explicitly omitted. This became problematic when dealing with very large installations. The only situation where this is useful is if you accidentally delete a directory in the package tree, leaving you with a whole bunch of dangling links. Note that you can enable the old approach with the -p option. Alternatively, you can use the --badlinks option get stow to search for dangling links in your target tree and remove the offenders manually.