.Dd July 28, 2013
.Dt RCUP 1
.Os
.Sh NAME
.Nm rcup
.Nd update and install dotfiles
.Sh SYNOPSIS
.Nm rcup
.Op Fl vq
.Op Fl t Ar tag
.Op Fl d Ar dir
.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 v
increase verbosity. This can be repeated for extra verbosity.
.It Fl q
decrease verbosity
.It Fl t Ar TAG
install dotfiles according to
.Ar TAG
.It Fl d Ar DIR
install dotfiles from the
.Ar DIR
\&. This can be specified multiple times.
.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