Ubuntu Manpage: rcup — update and install dotfiles managed by rcm

NAME

       rcup — update and install dotfiles managed by rcm

SYNOPSIS

       rcup  [-CfhiKkqVv]  [-B  hostname]  [-d  dir]  [-g]  [-I  excl_pat]  [-S excl_pat] [-s excl_pat] [-t tag]
            [-U excl_pat] [-u excl_pat] [-x excl_pat] [files ...]

DESCRIPTION

This is a program to update and install personal dotfiles. These dotfiles are managed in a separate
directory. Use rcup to install files from your dotfiles directories or from host- or tag-specific
directories within.

See “DIRECTORY LAYOUT” for details on the directory layout.

It supports these options:

-B HOSTNAME treat host-HOSTNAME as the host-specific directory instead of computing it

-C copy the files instead of symlinking them

-d DIR install dotfiles from the DIR. This can be specified multiple times.

-f if the rc file already exists in your home directory but does not match the file in your
dotfiles directory, remove the rc file then create the symlink

-g print to stdout a standalone shell script that will run the rcup command as specified.
Nothing on your filesystem will be modified by rcup when this flag is passed.

-h show usage instructions.

-I EXCL_PAT install rc files that match EXCL_PAT despite being excluded by the -x flag or a setting in
rcrc(5). This can be repeated with additional patterns. See lsrc(1), “EXCLUDE PATTERN”, for
more details.

-i if the rc file already exists in your home directory but does not match the file in your
dotfiles directory, prompt for how to handle it. This is the default

-K skip pre- and post-hooks

-k run pre- and post-hooks (see “DIRECTORY LAYOUT” for more details on hooks). This is the
default.

-S EXCL_PAT any rc file that matches EXCL_PAT is installed as if it were a file (using a symlink)
instead of as if it were a directory (by making a directory). This option can be repeated.

-s EXCL_PAT any file that matches EXCL_PAT is installed as normal, in accordance with the “ALGORITHM”
section below. This is the opposite of -S. This option can be repeated.

-t TAG install dotfiles according to TAG

-U EXCL_PAT any rc file that matches EXCL_PAT is installed without a leading dot. This option can be
repeated. See the documentation of the -U option in lsrc(1) for more information.

-u EXCL_PAT any rc file that matches EXCL_PAT is installed with a leading dot. This is the opposite of
-U. This option can be repeated. This is the default. See the documentation of the -u
option in lsrc(1) for more information.

-q decrease verbosity

-V show the version number.

-v increase verbosity. This can be repeated for extra verbosity. Verbose messages are printed
to stderr.

-x EXCL_PAT do not install rc files that match EXCL_PAT. This can be repeated with additional patterns.
See lsrc(1), “EXCLUDE PATTERN”, for more details.

files only install the specified file(s)

DIRECTORY LAYOUT

Any non-dot non-meta file or directory under your dotfiles directory will be installed as a dotfile. For
example, .dotfiles/zshrc will be installed into ~/.zshrc .

Files are installed as symlinks. Directories are installed by making directories. The -C flag causes
files to be installed as copies instead of symlinks. The COPY_ALWAYS option in rcrc(5) can be used to
list files that must only be copied.

Three meta files are supported: host-specific files, tagged files, hooks.

Host-specific files go in a directory named for the host, prefixed with host-. For example,
.dotfiles/host-scarlett contains files specific to the computer with hostname scarlett, and these files
will only be installed on the computer with hostname scarlett.

Tagged files go in a directory named for the tag, prefixed with tag-. Therefore, files under
.dotfiles/tag-git are only installed when installing using the git tag.

Hooks go in a directory named hooks. Two hooks are supported by rcup: pre-up and post-up. These go in
files or directories with predictable filenames: .dotfiles/hooks/pre-up and .dotfiles/hooks/post-up, or
.dotfiles/hooks/pre-up/* and .dotfiles/hooks/post-up/*. These files must be executable. They are run
every time rcup is run, and therefore must be idempotent.

Hooks will be executed one at a time, sorted alphabetically. For instance, hooks/pre-up/animals will run
before hooks/pre-up/aquariums, and hooks/pre-up/4-eyes will run before
hooks/post-up/2-u-nothing-compares.

ALGORITHM

       It is instructive to understand the process rcup uses when synchronizing your rc files:

       1.   The pre-up hook is run.

       2.   All  non-host,  non-tag files without a dot prefix are symlinked to the dotted filename in your home
            directory. So, .dotfiles/tigrc is symlinked to ~/.tigrc.

       3.   All non-host, non-tag directories have their structure copied to your home directory,  then  a  non-
            dotted  symlink  is  created  within.  So for example, .dotfiles/vim/autoload/haskell.vim causes the
            ~/.vim/autoload directory to be created, then haskell.vim is symlinked within.

       4.   Steps (2) and (3) are applied to host-specific files.  These  are  files  under  a  directory  named
            host-$HOSTNAME.

       5.   Steps  (2)  and  (3)  are  applied  to  tag-specific  files. These are files under directories named
            tag-$TAG_NAME, where $TAG_NAME is the name of each specified tag in turn,  taken  from  the  command
            line or from rcrc(5).

       6.   The post-up hook is run.

ENVIRONMENT

       RCRC  User configuration file. Defaults to ~/.rcrc.

FILES

       ~/.dotfiles ~/.rcrc

AUTHORS

       rcup is maintained by Mike Burns <mburns@thoughtbot.com> and thoughtbot: http://thoughtbot.se

Debian                                            July 28, 2013                                          RCUP(1)