4.2 Types And Syntax Of Ignore Lists

If you put Perl regular expressions, one per line, in a .stow-local-ignore file within any top level package directory, in which case any file or directory within that package matching any of these regular expressions will be ignored. In the absence of this package-specific ignore list, Stow will instead use the contents of ~/.stow-global-ignore, if it exists. If neither the package-local or global ignore list exist, Stow will use its own built-in default ignore list, which serves as a useful example of the format of these ignore list files:

# Comments and blank lines are allowed.

RCS
.+,v

CVS
\.\#.+       # CVS conflict files / emacs lock files
\.cvsignore

\.svn
_darcs
\.hg

\.git
\.gitignore

.+~          # emacs backup files
\#.*\#       # emacs autosave files

^/README.*
^/LICENSE.*
^/COPYING

Stow first iterates through the chosen ignore list (built-in, global, or package-local) as per above, stripping out comments (if you want to include the ‘#’ symbol in a regular expression, escape it with a blackslash) and blank lines, placing each regular expressions into one of two sets depending on whether it contains the ‘/’ forward slash symbol.

Then in order to determine whether a file or directory should be ignored:

1. Stow calculates its path relative to the top-level package directory, prefixing that with ‘/’. If any of the regular expressions containing a ‘/’ exactly⁴ match a subpath⁵ of this relative path, then the file or directory will be ignored.
2. If none of the regular expressions containing a ‘/’ match in the manner described above, Stow checks whether the basename⁶ of the file or directory matches exactly against the remaining regular expressions which do not contain a ‘/’, and if so, ignores the file or directory.
3. Otherwise, the file or directory is not ignored.

For example, if a file bazqux is in the foo/bar subdirectory of the package directory, Stow would use ‘/foo/bar/bazqux’ as the text for matching against regular expressions which contain ‘/’, and ‘bazqux’ as the text for matching against regular expressions which don’t contain ‘/’. Then regular expressions ‘bazqux’, ‘baz.*’, ‘.*qux’, ‘bar/.*x’, and ‘^/foo/.*qux’ would all match (causing the file to be ignored), whereas ‘bar’, ‘baz’, ‘qux’, and ‘o/bar/b’ would not (although ‘bar’ would cause its parent directory to be ignored and prevent Stow from recursing into that anyway, in which case the file bazqux would not even be considered for stowing).

As a special exception to the above algorithm, any .stow-local-ignore present in the top-level package directory is always ignored, regardless of the contents of any ignore list, because this file serves no purpose outside the stow directory.