.Dd July 28, 2013
.Dt RCUP 1
.Os
.Sh NAME
.Nm rcup
.Nd update and install dotfiles
.Sh SYNOPSIS
.Nm rcup
.Op Fl Cfiqv
.Op Fl d Ar dir
.Op Fl e Ar excl_pat
.Op Fl I Ar excl_pat
.Op Fl t Ar tag
.Op Ar files ...
.Sh DESCRIPTION
This is a program to update and install personal dotfiles. These
dotfiles are managed in a separate directory. Use
.Nm rcup
to install files from your dotfiles directories or from host- or
tag-specific directories within.
.Pp
See
.Sx DIRECTORY LAYOUT
for details on the directory layout.
.Pp
It supports these options:
.Bl -tag
.It Fl C
copy the files instead of symlinking them
.It Fl d Ar DIR
install dotfiles from the
.Ar DIR .
This can be specified multiple times.
.It Fl e Ar EXCL_PAT
do not install rc files that match
.Ar EXCL_PAT .
This can be repeated with additional patterns. See
.Xr lsrc 1 ,
.Sx EXCLUDE PATTERN ,
for more details.
.It Fl 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
.It Fl 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
.It Fl I Ar EXCL_PAT
install rc files that match
.Ar EXCL_PAT
despite being excluded by the
.Fl e
flag or a setting in
.Xr rcrc 5 .
This can be repeated with additional patterns. See
.Xr lsrc 1 ,
.Sx EXCLUDE PATTERN ,
for more details.
.It Fl t Ar TAG
install dotfiles according to
.Ar TAG
.It Fl q
decrease verbosity
.It Fl v
increase verbosity. This can be repeated for extra verbosity.
.It Ar files
only install the specified file(s)
.El
.Sh DIRECTORY LAYOUT
Any non-dot non-meta file or directory under your dotfiles directory will be
installed as a dotfile. For example,
.Pa .dotfiles/zshrc
will be installed into
.Pa ~/.zshrc
\&.
.Pp
Files are installed as symlinks. Directories are installed by making
directories.
.Pp
Two meta files are supported: host-specific files and tagged files.
.Pp
Host-specific files go in a directory named for the host, prefixed with
.Pa host- .
For example,
.Pa .dotfiles/host-scarlett
contains files specific to the computer with hostname
.Pa scarlett
, and these files will only be installed on the computer with hostname
.Pa scarlett
\&.
.Pp
Tagged files go in a directory named for the tag, prefixed with
.Li tag- .
Therefore, files under
.Pa .dotfiles/tag-git
are only installed when installing using the
.Li git
tag.
.Sh ALGORITHM
It is instructive to understand the process
.Nm rcup
uses when synchronizing your rc files:
.Bl -enum
.It
All non-host, non-tag files without a dot prefix are symlinked to the
dotted filename in your home directory. So,
.Pa .dotfiles/tigrc
is
symlinked to
.Pa ~/.tigrc .
.It
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,
.Pa .dotfiles/vim/autoload/haskell.vim
causes the
.Pa ~/.vim/autoload
directory to be created, then
.Pa haskell.vim
is symlinked within.
.It
Steps (1) and (2) are applied to host-specific files. These are files
under a directory named
.Sm off
.Pa host- Va $HOSTNAME .
.Sm on
.It
Steps (1) and (2) are applied to tag-specific files. These are files
under directories named
.Sm off
.Pa tag- Va $TAG_NAME ,
.Sm on
where
.Va $TAG_NAME
is the name of each specified tag in turn, taken from the command line
or from
.Xr rcrc 5 .
.El
.
.Sh FILES
.Pa ~/.dotfiles
.Pa ~/.rcrc
.Sh SEE ALSO
.Xr lsrc 1 ,
.Xr mkrc 1 ,
.Xr rcdn 1 ,
.Xr rcrc 5 ,
.Xr rcm 7
.Sh AUTHORS
.An "Mike Burns" Aq mike@mike-burns.com