1 files changed, 246 insertions, 0 deletions
diff --git a/man/rcm.7.mustache b/man/rcm.7.mustache
new file mode 100644
index 0000000..8956e5d
--- /dev/null
+++ b/man/rcm.7.mustache
@@ -0,0 +1,246 @@
+.Dd July 28, 2013
+.Dt RCM 7
+.Os
+.Sh NAME
+.Nm rcm
+.Nd dotfile management
+.Sh SYNOPSIS
+.Nm lsrc
+.Nm mkrc
+.Nm rcdn
+.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 committing your rc files to a central repository
+to share, but it also scales to a more complex situation such as
+multiple 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 FOR EXISTING DOTFILES DIRECTORIES
+This section is for those who already have an existing dotfiles
+directory; this directory is
+.Pa ~/.dotfiles ;
+the directory only contains rc files; and these rc filenames do not
+begin with a period. See the caveats below if this is not you.
+.Bl -enum
+.It
+Dryrun with
+.Xr lsrc 1 .
+Look for anything unexpected in here, such as
+.Pa ~/.install
+or
+.Pa ~/.Makefile ,
+or an empty list of dotfiles.
+.Pp
+.Dl lsrc
+.It
+Update any symlinks with
+.Xr rcup 1 .
+This is likely to do nothing, since your dotfiles already exist.
+.Pp
+.Dl rcup -v
+.It
+When necessary, add new rc files with
+.Xr mkrc 1 .
+.Pp
+.Dl mkrc ~/.tigrc
+.El
+.Ss COMMON PROBLEM: EXISTING INSTALL SCRIPTS
+Many existing dotfile directories have scripts named
+.Pa install
+or
+.Pa Makefile
+in the directory directory. This will cause a
+.Pa ~/.install
+or
+.Pa ~/.Makefile
+symlink to be created in your home
+directory. Use an exclusion pattern to ignore these.
+.Pp
+.Dl rcup -x install -x Rakefile -x Makefile -x install.sh
+.Ss COMMON PROBLEM: DOTTED FILENAMES IN DOTFILES DIRECTORY
+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.
+.Pp
+.Dl find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/\.//'` \;
+.Pp
+Note that this will break any existing symlinks. Those can be safely
+removed using the
+.Xr rcdn 1
+command.
+.Pp
+.Dl rcdn -v
+.Ss COMMON PROBLEM: DOTFILES DIRECTORY NOT IN Pa ~/.dotfiles
+This all assumes that your dotfiles directory is
+.Pa ~/.dotfiles .
+If it is elsewhere and you do not want to move it you can use the
+.Fl d Ar DIR
+option to
+.Xr rcup 1
+or modify
+.Ev DOTFILES_DIRS
+in
+.Xr rcrc 5 .
+.Pp
+.Dl rcup -d configs -v
+.
+.Sh QUICK START FOR EMPTY DOTFILES DIRECTORIES
+This section is for those who do not have an existing dotfiles
+directory and whose dotfiles are standard.
+.Bl -enum
+.It
+Add your rc files to a dotfiles directory with
+.Xr mkrc 1 .
+.Pp
+.Dl mkrc .zshrc .gitconfig .tigrc
+.It
+Synchronize your home directory with
+.Xr rcup 1
+.Pp
+.Dl rcup -v
+.El
+.Pp
+This will give you a directory named
+.Pa ~/.dotfiles
+with your dotfiles in it. Your original dotfiles will be symlinks into
+this directory. For example,
+.Pa ~/.zshrc
+will be a symlink to
+.Pa ~/.dotfiles/zshrc .
+.
+.Sh TAGGED DOTFILES
+This suite becomes more powerful if you share your dotfiles directory
+between computers, either because multiple people share the same
+directory or because you have multiple computers.
+.Pp
+If you 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.
+.Bl -enum
+.It
+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
+file into it using
+.Xr mkrc 1
+and passing the
+.Fl t
+option.
+.Pp
+.Dl mkrc -t zsh .zshrc
+.It
+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 with the
+.Ev TAGS
+variable.
+.Pp
+.Dl rcup -t zsh
+.El
+.
+.Sh MULTIPLE DOTFILE DIRECTORIES
+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
+The following 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
+.Dl rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles
+.Pp
+An exclusion pattern can be tied to a specific dotfiles directory.
+.Pp
+.Dl rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc'
+.
+.Sh HOST-SPECIFIC DOTFILES
+You can also mark host-specific files. This will go by the hostname. The
+.Xr rcrc 5
+configuration
+file is a popular candidate for a host-specific file, since the tags and
+dotfile directories listed in there are often specific to a single
+machine.
+.Pp
+.Dl mkrc -o .rcrc
+.
+.Sh RATIONALE
+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 rcdn 1 ,
+.Xr rcup 1 ,
+.Xr rcrc 5
+.Sh AUTHORS
+.Nm
+is maintained by
+.An "Mike Burns" Aq Mt mburns@thoughtbot.com
+and
+.Lk http://thoughtbot.se thoughtbot
+.Sh CONTRIBUTORS
+.An -split
+{{#contributors}}
+.An "{{{name}}}" Aq Mt {{{email}}}
+{{/contributors}}