.Dd July 28, 2013
.Dt RCM 7
.Os
.Sh NAME
.Nm rcm
.Nd dotfile management
.Sh SYNOPSIS
.Nm lsrc
.Nm mkrc
.Nm rcup
.Sh DESCRIPTION
The rcm suite of tools is for managing dotfiles directories. This is a
directory containing all the
.Li .*rc
files in your home directory
.Sm off
.Po
.Pa .zshrc ,
.Sm on
.Pa .vimrc ,
and so on
.Pc .
These files have gone by many
names in history, such as 
.Do
rc files
.Dc
because they typically end in
.Li rc
or 
.Do
dotfiles
.Dc
because they begin with a period.
.Pp
This suite is useful, for example, for commiting your rc files to a
central repository to share on GitHub, but it also scales to a more
complex situation such as mutliple source directories shared between
computers with some host-specific or task-specific files.
.Pp
This guide serves as a tutorial motivating the suite. For a list of
quick reference documentation see the
.Sx SEE ALSO
section below.
.
.Sh QUICK START
If you do not already have a dotfiles directory then we can get started
quickly. Use the
.Xr mkrc 1
command to add files to the directory.
.Pp
.Dl mkrc .vimrc
.Pp
You can see the effects of this with
.Xr lsrc 1 .
.Pp
.Dl lsrc
.Pp
The default dotfiles directory is
.Pa $HOME/.dotfiles .
The
.Xr mkrc 1
command will move
.Pa .vimrc
to
.Pa .dotfiles/vimrc ,
then symlink
.Pa .vimrc
to
.Pa .dotfiles/vimrc .
.Pp
This suite becomes more powerful when you share your dotfiles directory
between computers, either because mutliple people share the same
directory or because you have mutliple computers. As a quick simulation,
we can create a file in your new
.Pa .dotfiles
directory.
.Pp
.Dl echo TAGS="zsh" > ~/.dotfiles/rcrc
.Pp
We can update our home directory to have a new
.Pa .rcrc
file (a symlink to
.Pa .dotfiles/rcrc )
using the
.Xr rcup 1
command.
.Pp
.Dl rcup -v
.Pp
We passed the
.Fl v
option to see in more explicit detail what it
does. All rcm commands take the
.Fl v
option, and mutliple
.Fl v
options can be given to give more explicit detail.
.Pp
If you do share the dotfiles directory between people, you may end up
with some irrelevant or even incorrect rc files. For example, you may
have a
.Pa .zshrc
while your other contributor has a
.Pa .bashrc .
This situation can be handled with tags.
.Pp
A tag is a directory under the dotfiles directory the starts with the
letters
.Li tag- .
We can handle the competing shell example by
making a
.Pa tag-zsh
directory and moving the
.Pa .zshrc
into it.
.Pp
.Dl mkrc -t zsh .zshrc
.Pp
And likewise, your dotfiles partner would do the same for
.Pa .bashrc .
.Pp
.Dl mkrc -t bash .bashrc
.Pp
When updating with
.Xr rcup 1
you can pass the
.Fl t
option to
include the tags you want. This can also be set in the
.Xr rcrc 5
configuration file, as hinted at above.
.Pp
.Dl rcup -t zsh
.Pp
The tags are useful for sharing a single dotfiles directory between
competers or people, but another common situation is combining multiple
dotfiles directories that people have shared with you. For this we have
the
.Fl d
flag or the
.Ev DOTFILES_DIRS
option in
.Pa .rcrc .
.Pp
.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles
.Pp
This rcup invocation will go in sequence through the three dotfiles
directories, updating any symlinks as needed. Any overlapping rc files
will use the first result, not the last; that is,
.Pa .dotfiles/vimrc
will take precedence over
.Pa marriage-dotfiles/vimrc .
.Pp
In a similar use case to tags you can also have host-specific files
marked. This will go by the hostname. The
.Xr rcrc 5
configuration
file is a popular candidate for a host-specific file.
.Pp
.Dl mkdir .dotfiles/host-`hostname`
.Dl mv .rcrc .dotfiles/host-`hostname`/rcrc
.Dl rcup -v
.Pp
.Sh MIGRATING EXISTING WORKFLOWS
Many people have existing dotfiles directories, and have been managing
them using custom scripts. The suite of tools in this package should be
able to replace your custom scripts with little effort.
.Pp
When converting an existing dotfiles directory you do need some
knowledge of how rcm works and what it expects. Details can be found in
.Xr rcup 1 ,
but briefly:
.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.
.It
Steps (1) and (2) are applied to tag-specific files.
.El
.Pp
Two alternative conventions in dotfile directories can cause issue with
this. The most common problem is to have a file named
.Pa install
or
.Pa Makefile
in your dotfiles directory. This will cause a
.Pa ~/.install
or
.Pa ~/.Makefile
symlink to be created in your home
directory. The best option here is to move that file outside of your
dotfiles directory, or remove it entirely.
.Pp
A less common situation is for all the filenames in your dotfiles
directory to be prefixed with a period. These files are skipped by the
rcm suite, and thus would result in nothing happening. The only option
in this case is to rename all the files, for example by using a shell
command like the following. Note that this will break any existing
symlinks.
.Pp
.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \;
.Pp
The easiest way to see what the rcm suite will do is to run the
.Xr lsrc 1
command. This shows all the symlinks that the suite intends
to maintain.
.Pp
Once you are satisfied and ready to try rcm, use the
.Xr rcup 1
command.
.Pp
.Sh WHY RCM
The rcm suite was built as an abstraction over the shell, Ruby, Python,
and make scripts people were writing and sharing. It is intended to run
on any unix system and support the range from simple to complex dotfile
directories.
.Pp
As such, this suite is useful as a common base. Through this we can
share tools and develop this further as a first-class entity. It is also
our hope that a common set of tools will encourage others to share their
dotfiles, too.
.Sh FILES
.Pa ~/.dotfiles
.Pa ~/.rcrc
.Sh SEE ALSO
.Xr lsrc 1 ,
.Xr mkrc 1 ,
.Xr rcup 1 ,
.Xr rcrc 5
.Sh AUTHORS
.An "Mike Burns" Aq mike@mike-burns.com