---
title: rcm, an rc file manager
teaser: Announcing a new open source library, rcm, for managing dotfiles.
tags: unix,open source
author: Mike Burns
published_on: 2014-02-06
---

We have built a suite of tools for managing your rc files.

The rcm suite of tools is for managing [dotfiles][thoughtbot-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. Creative, I
know.

It's a unification of the existing shell scripts, make targets, rake
tasks, GNU Bash constructions, and Python hacks that people copy and
paste into their dotfiles repo, with a classical unix flair.

Here's a very quick example:

    % lsrc
    /home/mike/.zshrc:/home/mike/.dotfiles/zshrc
    % rcup
    linking /home/mike/.zshrc

This blog post demonstrates the features, but you may want to [install
rcm][installation-instructions] and run through [the tutorial][rcm7] too.

## Build on it

Once unified, we extended the suite with support for sharing rc files
via host-specific files, tags, multiple dotfile directories, and hooks.

A little something for the sysadmins out there, _host-specific
files_ automate the configuration you need to do on each host.
Maybe the computer `jupiter` needs a `.gitconfig` but the computer
`mars` needs a `.mailrc`. You'd put the `.gitconfig` in
`host-jupiter/gitconfig`, and the `.mailrc` in `host-mars/mailrc`, and
our suite takes care of the rest.

The next step up from host-specific is _tagging_: tag the `.mailrc` file
as `mailx` (`tag-mailx/mailrc`) and `.gitconfig` as `git`
(`tag-git/gitconfig`), and install and uninstall the tags as needed:

    % rcup -t mailx
    % rcdn -t mailx

Tagging is great for teams sharing the same dotfiles repo, but we can do
better. While some of us come to computers with a blank slate, others
come with well over a decade of fine-tuned rc files. Let them _combine
dotfiles repos_, preferring theirs:

    % rcup -d personal-dotfiles -d thoughtbot-dotfiles

While automating things we noticed that some things require setup. For
example, after linking the `.vimrc` you need to run `:BundleInstall`.
This is why we added _hooks_, such as the one in the thoughtbot dotfiles
as [`hooks/post-up`][thoughtbot-post-up]:

    #!/bin/sh

    if [ ! -e $HOME/.vim/bundle/vundle ]; then
      git clone https://github.com/gmarik/vundle.git $HOME/.vim/bundle/vundle
    fi
    vim -u $HOME/.vimrc.bundles +BundleInstall +qa

## Automate it

We make it easier to add something to your dotfiles, too. This is great
for getting started, but it's also great for experimentation. For
example, add your `.cshrc` to the `openbsd` tag:

    % mkrc -t openbsd .cshrc

Or get fancy by adding a host-specific file to the dotfiles repo you
share with your brunch friends:

    % mkrc -o -d the-brunch-dotfiles .rcrc

## Configure it

Given the power, we had to make an rc file for our rc files. Enter
`.rcrc`.

The simplest things to configure are your tags and source directories:

    TAGS="openbsd mailx gnupg"
    DOTFILES_DIRS="~/.dotfiles /usr/local/share/global-dotfiles"

Some files should never be symlinks:

    COPY_ALWAYS=weechat/*

And some files should be excluded:

    EXCLUDES=global-dotfiles:python*

This means a normal `rcup` will do the right thing, without thinking
hard about what you have configured, which machine you're on, or what
has changed in your shared repos.

The `.rcrc` file is perfect as a host-specific file in your personal
dotfiles repo:

    mkrc -o .rcrc

## Read about it

Since this is a unix tool, we treat it like a unix tool. Read the full
tutorial in [the `rcm(7)` manpage][rcm7], read about each individual
tool (with examples) in the respective [`lsrc(1)`][lsrc1],
[`rcup(1)`][rcup1], [`rcdn(1)`][rcdn1], and [`mkrc(1)`][mkrc1] manpages,
and the full configuration file is in the [`rcrc(5)`][rcrc5] manpage.

The traditional `whatis` command will jog your memory:

    % whatis rcm
    rcup (1)             - update and install dotfiles
    rcdn (1)             - remove dotfiles
    lsrc (1)             - show configuration files
    mkrc (1)             - bless files into a dotfile
    rcrc (5)             - configuration for rcm
    rcm (7)              - dotfile management

## Install anywhere

The rcm suite is written in POSIX sh, available out of the box on BSD,
GNU, OS X, and many other systems. We do our best to keep it
portable.

The source package can be installed using GNU autotools, as is typical
for many projects:

    % configure
    % gmake
    % gmake install

But it gets easier on Arch and Debian, which are supported by their
native package managers. Check our [installation
instructions][installation-instructions] for the details on those.

We also support OS X using Homebrew from our new thoughtbot tap:

    % brew tap thoughtbot/formulae
    % brew install rcm

Watch that tap for other tools for command line champions.

## Get started quickly

Instead of inventing something new, we decided to codify existing
practices. If you have a dotfiles repo much like ours—one where all
the normal files should be symlinked as dotted files in your home
directory—you can get started immediately:

    % lsrc -d ~/dotfiles
    % rcup -v -d ~/dotfiles

If you have no dotfiles repo yet, you can get started instantly:

    % mkrc .zshrc .vimrc

We also cover special cases in [our tutorial][rcm7].

## Let's build this

Please share your feedback on [GitHub][github-rcm]. Together we can
build the greatest rc file management suite.

## What's next

* Install rcm using [our instructions][installation-instructions].
* Use or fork [our dotfiles][thoughtbot-dotfiles].

[thoughtbot-dotfiles]: https://github.com/thoughtbot/dotfiles/
[thoughtbot-dotfiles-forks]: https://github.com/thoughtbot/dotfiles/network
[rcm7]: http://thoughtbot.github.io/rcm/rcm.7.html
[lsrc1]: http://thoughtbot.github.io/rcm/lsrc.1.html
[rcup1]: http://thoughtbot.github.io/rcm/rcup.1.html
[rcdn1]: http://thoughtbot.github.io/rcm/rcdn.1.html
[mkrc1]: http://thoughtbot.github.io/rcm/mkrc.1.html
[rcrc5]: http://thoughtbot.github.io/rcm/rcrc.5.html
[installation-instructions]: https://github.com/thoughtbot/rcm#installation
[thoughtbot-post-up]: https://github.com/thoughtbot/dotfiles/blob/master/hooks/post-up
[github-rcm]: https://github.com/thoughtbot/rcm