(stow.info)Types And Syntax Of Ignore Lists

---

Next: Justification For Yet Another Set Of Ignore Files Prev: Motivation For Ignore Lists Up: Ignore Lists

---

Enter node , (file) or (file)node

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_(1) match a subpath(2) 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_(3) 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.

   ---------- Footnotes ----------

   (1) Exact matching means the regular expression is anchored at the
beginning and end, in contrast to unanchored regular expressions which
will match a substring.

   (2) In this context, "subpath" means a contiguous subset of path
segments; e.g for the relative path `one/two/three', there are six
valid subpaths: `one', `two', `three', `one/two', `two/three',
`one/two/three'.

   (3) The "basename" is the name of the file or directory itself,
excluding any directory path prefix - as returned by the `basename'
command.