Resource Files (Stow)

## 11 Resource Files

Default command line options may be set in `.stowrc` (current directory) or `~/.stowrc` (home directory). These are parsed in that order, and are appended together if they both exist. The effect of the options in the resource file is similar to simply prepending the options to the command line. This feature can be used for some interesting effects.

For example, suppose your site uses more than one stow directory, perhaps in order to share around responsibilities with a number of systems administrators. One of the administrators might have the following in their `~/.stowrc` file:

    --dir=/usr/local/stow2
    --target=/usr/local
    --ignore='~'
    --ignore='^CVS'

so that the `stow` command will default to operating on the `/usr/local/stow2` directory, with `/usr/local` as the target, and ignoring vi backup files and CVS directories.

If you had a stow directory `/usr/local/stow/perl-extras` that was only used for Perl modules, then you might place the following in `/usr/local/stow/perl-extras/.stowrc`:

    --dir=/usr/local/stow/perl-extras
    --target=/usr/local
    --override=bin
    --override=man
    --ignore='perllocal\.pod'
    --ignore='\.packlist'
    --ignore='\.bs'

so that when you are in the `/usr/local/stow/perl-extras` directory, `stow` will regard any subdirectories as stow packages, with `/usr/local` as the target (rather than the immediate parent directory `/usr/local/stow`), overriding any pre-existing links to bin files or man pages, and ignoring some cruft that gets installed by default.

If an option is provided both on the command line and in a resource file, the command line option takes precedence. For options that provide a single value, such as `--target` or `--dir`, the command line option will overwrite any options in the resource file. For options that can be given more than once, `--ignore` for example, command line options and resource options are appended together.

For options that take a file path, environment variables and the tilde character (`~`) are expanded. An environment variable can be given in either the `$VAR` or `${VAR}` form. To prevent expansion, escape the `$` or `~` with a backslash. Since these values are first subject to standard shell quoting rules, if you want special characters such as `\b` or `$` to be treated as regular expression assertions then they will need extra escaping, i.e. `\\b` and `\\\$` respectively.

The options `-D`, `-S`, and `-R` are ignored in resource files. This is also true of any package names given in the resource file.