NAME

     rcm — dotfile management

SYNOPSIS

     lsrc
     mkrc
     rcdn
     rcup

DESCRIPTION

     The rcm suite of tools is for managing dotfiles directories. This is a directory containing
     all the .*rc files in your home directory (.zshrc, .vimrc, and so on).  These files have
     gone by many names in history, such as “rc files” because they typically end in rc or
     “dotfiles” because they begin with a period.

     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.

     This guide serves as a tutorial motivating the suite. For a list of quick reference
     documentation see the SEE ALSO section below.

QUICK START FOR EXISTING DOTFILES DIRECTORIES

     This section is for those who already have an existing dotfiles directory; this directory is
     ~/.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.

     1.   Dry run with lsrc(1).  Look for anything unexpected in here, such as ~/.install or
          ~/.Makefile, or an empty list of dotfiles.

                lsrc

     2.   Update any symlinks with rcup(1).  This is likely to do nothing, since your dotfiles
          already exist.

                rcup -v

     3.   When necessary, add new rc files to the dotfiles directory with mkrc(1).

                mkrc ~/.tigrc

          In the other direction, you can use rcup(1) to create the symlinks from ~/.dotfiles to
          your home directory.

                rcup tigrc

   COMMON PROBLEM: EXISTING INSTALL SCRIPTS
     Many existing dotfile directories have scripts named install or Makefile in the directory.
     This will cause a ~/.install or ~/.Makefile symlink to be created in your home directory.
     Use an exclusion pattern to ignore these.

           rcup -x install -x Rakefile -x Makefile -x install.sh

   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.

           find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed 's/.//'` ;

     Note that this will break any existing symlinks. Those can be safely removed using the
     rcdn(1) command.

           rcdn -v

   COMMON PROBLEM: DOTFILES DIRECTORY NOT IN ~/.dotfiles
     This all assumes that your dotfiles directory is ~/.dotfiles.  If it is elsewhere and you do
     not want to move it you can use the -d DIR option to rcup(1) or modify DOTFILES_DIRS in
     rcrc(5).

           rcup -d configs -v

   COMMON PROBLEM: CONFIGURATION FILES/DIRECTORIES WITHOUT DOTS
     By default, the rcm suite will prefix every file and directory it manages with a dot. If
     that is not desired, for example in the case of ~/bin or ~/texmf, you can add that file or
     directory to UNDOTTED in rcrc(5) or use the -U option. For example:

           mkrc -U bin

QUICK START FOR EMPTY DOTFILES DIRECTORIES

     This section is for those who do not have an existing dotfiles directory and whose dotfiles
     are standard.

     1.   Add your rc files to a dotfiles directory with mkrc(1).

                mkrc .zshrc .gitconfig .tigrc

     2.   Synchronize your home directory with rcup(1)

                rcup -v

     This will give you a directory named ~/.dotfiles with your dotfiles in it. Your original
     dotfiles will be symlinks into this directory. For example, ~/.zshrc will be a symlink to
     ~/.dotfiles/zshrc.

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.

     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 .zshrc while your other contributor has
     a .bashrc.  This situation can be handled with tags.

     1.   A tag is a directory under the dotfiles directory that starts with the letters tag-.
          We can handle the competing shell example by making a tag-zsh directory and moving the
          .zshrc file into it using mkrc(1) and passing the -t option.

                mkrc -t zsh .zshrc

     2.   When updating with rcup(1) you can pass the -t option to include the tags you want.
          This can also be set in the rcrc(5) configuration file with the TAGS variable.

                rcup -t zsh

MULTIPLE DOTFILE DIRECTORIES

     Another common situation is combining multiple dotfiles directories that people have shared
     with you. For this we have the -d flag or the DOTFILES_DIRS option in .rcrc.

     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, .dotfiles/vimrc will take precedence over marriage-dotfiles/vimrc.

           rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles

     An exclusion pattern can be tied to a specific dotfiles directory.

           rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc'

HOST-SPECIFIC DOTFILES

     You can also mark host-specific files. This will go by the hostname. The 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.

           mkrc -o .rcrc

     If your hostname is difficult to compute, or you otherwise want to use a different hostname,
     you can use the -B flag.

           mkrc -B eggplant .rcrc

STANDALONE INSTALLATION SCRIPT

     The rcup(1) tool can be used to generate a portable shell script.  Instead of running a
     command such as ln(1) or rm(1), it will print the command to stdout.  This is controlled
     with the -g flag.  Note that this will generate a script to create an exact replica of the
     synchronization, including tags, host-specific files, and dotfiles directories.

           env RCRC=/dev/null rcup -B 0 -g > install.sh

     Using the above command, you can now run install.sh to install (or re-install) your rc
     files.  The install.sh script can be stored in your dotfiles directory, copied between
     computers, and so on.

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.

     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.

FILES

     ~/.dotfiles ~/.rcrc

SEE ALSO

     lsrc(1), mkrc(1), rcdn(1), rcup(1), rcrc(5)

AUTHORS

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