The default action of Stow is to install a package. This means creating symlinks in the target tree that point into the package tree. Stow attempts to do this with as few symlinks as possible; in other words, if Stow can create a single symlink that points to an entire subtree within the package tree, it will choose to do that rather than create a directory in the target tree and populate it with symlinks.
For example, suppose that no packages have yet been installed in /usr/local; it’s completely empty (except for the stow subdirectory, of course). Now suppose the Perl package is installed. Recall that it includes the following directories in its installation image: bin; info; lib/perl; man/man1. Rather than creating the directory /usr/local/bin and populating it with symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (and so on), Stow will create a single symlink, /usr/local/bin, which points to stow/perl/bin. In this way, it still works to refer to /usr/local/bin/perl and /usr/local/bin/a2p, and fewer symlinks have been created. This is called tree folding, since an entire subtree is “folded” into a single symlink.
To complete this example, Stow will also create the symlink /usr/local/info pointing to stow/perl/info; the symlink /usr/local/lib pointing to stow/perl/lib; and the symlink /usr/local/man pointing to stow/perl/man.
Now suppose that instead of installing the Perl package into an empty target tree, the target tree is not empty to begin with. Instead, it contains several files and directories installed under a different system-administration philosophy. In particular, /usr/local/bin already exists and is a directory, as are /usr/local/lib and /usr/local/man/man1. In this case, Stow will descend into /usr/local/bin and create symlinks to ../stow/perl/bin/perl and ../stow/perl/bin/a2p (etc.), and it will descend into /usr/local/lib and create the tree-folding symlink perl pointing to ../stow/perl/lib/perl, and so on. As a rule, Stow only descends as far as necessary into the target tree when it can create a tree-folding symlink. However, this behaviour can be changed via the --no-folding option; see Invoking Stow.
The time often comes when a tree-folding symlink has to be undone because another package uses one or more of the folded subdirectories in its installation image. This operation is called splitting open or unfolding a folded tree. It involves removing the original symlink from the target tree, creating a true directory in its place, and then populating the new directory with symlinks to the newly-installed package and to the old package that used the old symlink. For example, suppose that after installing Perl into an empty /usr/local, we wish to install Emacs. Emacs’s installation image includes a bin directory containing the emacs and etags executables, among others. Stow must make these files appear to be installed in /usr/local/bin, but presently /usr/local/bin is a symlink to stow/perl/bin. Stow therefore takes the following steps: the symlink /usr/local/bin is deleted; the directory /usr/local/bin is created; links are made from /usr/local/bin to ../stow/emacs/bin/emacs and ../stow/emacs/bin/etags; and links are made from /usr/local/bin to ../stow/perl/bin/perl and ../stow/perl/bin/a2p.
When splitting open a folded tree, Stow makes sure that the symlink it is about to remove points inside a valid package in the current stow directory. Stow will never delete anything that it doesn’t own. Stow “owns” everything living in the target tree that points into a package in the stow directory. Anything Stow owns, it can recompute if lost: symlinks that point into a package in the stow directory, or directories that only contain symlinks that stow “owns”. Note that by this definition, Stow doesn’t “own” anything in the stow directory or in any of the packages.
If Stow needs to create a directory or a symlink in the target tree and it cannot because that name is already in use and is not owned by Stow, then a conflict has arisen. See Conflicts.