RCM(7) BSD Miscellaneous Information Manual RCM(7)NAMErcm — 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 direc‐
tory; 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 direc‐
tory 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 com‐
mand 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 direc‐
tory 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 mak‐
ing 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 dot‐
files 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
OS X users should see the BUGS section for more details.
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 dot‐
files 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 dot‐
files, too.
FILES
~/.dotfiles ~/.rcrc
SEE ALSOlsrc(1), mkrc(1), rcdn(1), rcup(1), rcrc(5)AUTHORSrcm is maintained by Mike Burns ⟨mburns@thoughtbot.com⟩ and thoughtbot:
http://thoughtbot.se
BUGS
For OS X systems, we strongly encourage the use of the HOSTNAME variable
in your rcrc(5). We use the hostname(1) program to determine the unique
identifier for the host. This program is not specified by POSIX and can
vary by system. On OS X the hostname is unpredictable, and can even
change as part of the DHCP handshake.
CONTRIBUTORS
Andrei Dziahel ⟨develop7@develop7.info⟩
Anton Ilin ⟨anton@ilin.dn.ua⟩
Ben Turrubiates ⟨ben@turrubiat.es⟩
Blake Williams ⟨blake@blakewilliams.me⟩
Caleb Land ⟨caleb@land.fm⟩
Carl van Tonder ⟨carl@supervacuo.com⟩
Christian Holtje ⟨docwhat@gerf.org⟩
Christian Höltje ⟨docwhat@gerf.org⟩
Christopher Koch ⟨ckoch@cs.nmt.edu⟩
Dan Croak ⟨dan@thoughtbot.com⟩
Daniel Watson ⟨dwatson@thig.com⟩
David Alexander ⟨davidpaulalexander@gmail.com⟩
Devraj Mehta ⟨devm33@gmail.com⟩
George Brocklehurst ⟨george@thoughtbot.com⟩
Jarkko Kniivilä ⟨jkniiv@gmail.com⟩
Jason Daniel Augustine Gilliland ⟨jdagilliland@gmail.com⟩
Javier López ⟨linux.kitten@gmail.com⟩
Joe Ferris ⟨jferris@thoughtbot.com⟩
John Axel Eriksson ⟨john@insane.se⟩
Jordan Eldredge ⟨jordaneldredge@gmail.com⟩
Martin Frost ⟨frost@ceri.se⟩
Melissa Xie ⟨melissa@thoughtbot.com⟩
Michael Reed ⟨supertron421@gmail.com⟩
Mike Burns ⟨mburns@thoughtbot.com⟩
Pablo Olmos de Aguilera Corradini ⟨pablo@glatelier.org⟩
Patrick Brisbin ⟨pat@thoughtbot.com⟩
Roberto Pedroso ⟨roberto@rpedroso.com⟩
Scott Stevenson ⟨scott@stevenson.io⟩
Teo Ljungberg ⟨teo@teoljungberg.com⟩
Vlad GURDIGA ⟨gurdiga@gmail.com⟩
Zach Latta ⟨zach@zachlatta.com⟩
BSD July 28, 2013 BSD
