rcm, an rc file manager

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

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. 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 and run through the tutorial 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:

#!/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, read about each individual tool (with examples) in the respective lsrc(1), rcup(1), rcdn(1), and mkrc(1) manpages, and the full configuration file is in the rcrc(5) 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 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.

Let’s build this

Please share your feedback on GitHub. Together we can build the greatest rc file management suite.

What’s next

Mike Burns

Hound automatically reviews Ruby, JavaScript, and CoffeeScript code in your GitHub pull requests and comments on style violations. It is free for open source repos and $12/month per private repo.