1RCM(7)               BSD Miscellaneous Information Manual               RCM(7)
2

NAME

4     rcm — dotfile management
5

SYNOPSIS

7     lsrc
8     mkrc
9     rcdn
10     rcup
11

DESCRIPTION

13     The rcm suite of tools is for managing dotfiles directories. This is a
14     directory containing all the .*rc files in your home directory (.zshrc,
15     .vimrc, and so on).  These files have gone by many names in history, such
16     as “rc files” because they typically end in rc or “dotfiles” because they
17     begin with a period.
18
19     This suite is useful for committing your rc files to a central repository
20     to share, but it also scales to a more complex situation such as multiple
21     source directories shared between computers with some host-specific or
22     task-specific files.
23
24     This guide serves as a tutorial motivating the suite. For a list of quick
25     reference documentation see the SEE ALSO section below.
26

QUICK START FOR EXISTING DOTFILES DIRECTORIES

28     This section is for those who already have an existing dotfiles direc‐
29     tory; this directory is ~/.dotfiles; the directory only contains rc
30     files; and these rc filenames do not begin with a period. See the caveats
31     below if this is not you.
32
33     1.   Dry run with lsrc(1).  Look for anything unexpected in here, such as
34          ~/.install or ~/.Makefile, or an empty list of dotfiles.
35
36                lsrc
37
38     2.   Update any symlinks with rcup(1).  This is likely to do nothing,
39          since your dotfiles already exist.
40
41                rcup -v
42
43     3.   When necessary, add new rc files to the dotfiles directory with
44          mkrc(1).
45
46                mkrc ~/.tigrc
47
48          In the other direction, you can use rcup(1) to create the symlinks
49          from ~/.dotfiles to your home directory.
50
51                rcup tigrc
52
53   COMMON PROBLEM: EXISTING INSTALL SCRIPTS
54     Many existing dotfile directories have scripts named install or Makefile
55     in the directory. This will cause a ~/.install or ~/.Makefile symlink to
56     be created in your home directory. Use an exclusion pattern to ignore
57     these.
58
59           rcup -x install -x Rakefile -x Makefile -x install.sh
60
61   COMMON PROBLEM: DOTTED FILENAMES IN DOTFILES DIRECTORY
62     A less common situation is for all the filenames in your dotfiles direc‐
63     tory to be prefixed with a period. These files are skipped by the rcm
64     suite, and thus would result in nothing happening. The only option in
65     this case is to rename all the files, for example by using a shell com‐
66     mand like the following.
67
68           find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed
69           's/.//'` ;
70
71     Note that this will break any existing symlinks. Those can be safely re‐
72     moved using the rcdn(1) command.
73
74           rcdn -v
75
76   COMMON PROBLEM: DOTFILES DIRECTORY NOT IN ~/.dotfiles
77     This all assumes that your dotfiles directory is ~/.dotfiles.  If it is
78     elsewhere and you do not want to move it you can use the -d DIR option to
79     rcup(1) or modify DOTFILES_DIRS in rcrc(5).
80
81           rcup -d configs -v
82
83   COMMON PROBLEM: CONFIGURATION FILES/DIRECTORIES WITHOUT DOTS
84     By default, the rcm suite will prefix every file and directory it manages
85     with a dot. If that is not desired, for example in the case of ~/bin or
86     ~/texmf, you can add that file or directory to UNDOTTED in rcrc(5) or use
87     the -U option. For example:
88
89           mkrc -U bin
90

QUICK START FOR EMPTY DOTFILES DIRECTORIES

92     This section is for those who do not have an existing dotfiles directory
93     and whose dotfiles are standard.
94
95     1.   Add your rc files to a dotfiles directory with mkrc(1).
96
97                mkrc .zshrc .gitconfig .tigrc
98
99     2.   Synchronize your home directory with rcup(1)
100
101                rcup -v
102
103     This will give you a directory named ~/.dotfiles with your dotfiles in
104     it. Your original dotfiles will be symlinks into this directory. For ex‐
105     ample, ~/.zshrc will be a symlink to ~/.dotfiles/zshrc.
106

TAGGED DOTFILES

108     This suite becomes more powerful if you share your dotfiles directory be‐
109     tween computers, either because multiple people share the same directory
110     or because you have multiple computers.
111
112     If you share the dotfiles directory between people, you may end up with
113     some irrelevant or even incorrect rc files. For example, you may have a
114     .zshrc while your other contributor has a .bashrc.  This situation can be
115     handled with tags.
116
117     1.   A tag is a directory under the dotfiles directory that starts with
118          the letters tag-.  We can handle the competing shell example by mak‐
119          ing a tag-zsh directory and moving the .zshrc file into it using
120          mkrc(1) and passing the -t option.
121
122                mkrc -t zsh .zshrc
123
124     2.   When updating with rcup(1) you can pass the -t option to include the
125          tags you want. This can also be set in the rcrc(5) configuration
126          file with the TAGS variable.
127
128                rcup -t zsh
129

MULTIPLE DOTFILE DIRECTORIES

131     Another common situation is combining multiple dotfiles directories that
132     people have shared with you. For this we have the -d flag or the
133     DOTFILES_DIRS option in .rcrc.
134
135     The following rcup invocation will go in sequence through the three dot‐
136     files directories, updating any symlinks as needed. Any overlapping rc
137     files will use the first result, not the last; that is, .dotfiles/vimrc
138     will take precedence over marriage-dotfiles/vimrc.
139
140           rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles
141
142     An exclusion pattern can be tied to a specific dotfiles directory.
143
144           rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc'
145

HOST-SPECIFIC DOTFILES

147     You can also mark host-specific files. This will go by the hostname. The
148     rcrc(5) configuration file is a popular candidate for a host-specific
149     file, since the tags and dotfile directories listed in there are often
150     specific to a single machine.
151
152           mkrc -o .rcrc
153
154     If your hostname is difficult to compute, or you otherwise want to use a
155     different hostname, you can use the -B flag.
156
157           mkrc -B eggplant .rcrc
158
159     macOS users should see the BUGS section for more details.
160

STANDALONE INSTALLATION SCRIPT

162     The rcup(1) tool can be used to generate a portable shell script.  In‐
163     stead of running a command such as ln(1) or rm(1), it will print the com‐
164     mand to stdout.  This is controlled with the -g flag.  Note that this
165     will generate a script to create an exact replica of the synchronization,
166     including tags, host-specific files, and dotfiles directories.
167
168           env RCRC=/dev/null rcup -B 0 -g > install.sh
169
170     Using the above command, you can now run install.sh to install (or re-in‐
171     stall) your rc files.  The install.sh script can be stored in your dot‐
172     files directory, copied between computers, and so on.
173

RATIONALE

175     The rcm suite was built as an abstraction over the shell, Ruby, Python,
176     and make scripts people were writing and sharing. It is intended to run
177     on any unix system and support the range from simple to complex dotfile
178     directories.
179
180     As such, this suite is useful as a common base. Through this we can share
181     tools and develop this further as a first-class entity. It is also our
182     hope that a common set of tools will encourage others to share their dot‐
183     files, too.
184

FILES

186     ~/.dotfiles ~/.rcrc
187

SEE ALSO

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

AUTHORS

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

BUGS

196     For macOS systems, we strongly encourage the use of the HOSTNAME variable
197     in your rcrc(5).  We use the hostname(1) program to determine the unique
198     identifier for the host. This program is not specified by POSIX and can
199     vary by system. On macOS, the hostname is unpredictable, and can even
200     change as part of the DHCP handshake.
201

CONTRIBUTORS

203     Alan Yee <alyee@ucsd.edu>
204     Alexander Goldstein <alexg@alexland.org>
205     Andrei Dziahel <develop7@develop7.info>
206     Anton Ilin <anton@ilin.dn.ua>
207     Ben Stephens <BKStephens@outlook.com>
208     Ben Turrubiates <ben@turrubiat.es>
209     Blake Williams <blake@blakewilliams.me>
210     Caleb Land <caleb@land.fm>
211     Carl van Tonder <carl@supervacuo.com>
212     Casey Rodarmor <casey@rodarmor.com>
213     Christian Höltje <docwhat@gerf.org>
214     Christian Höltje <docwhat@gerf.org>
215     Christopher Koch <ckoch@cs.nmt.edu>
216     Dan Croak <dan@thoughtbot.com>
217     Daniel Watson <dwatson@thig.com>
218     Darcy Parker <darcyparker@gmail.com>
219     David Alexander <davidpaulalexander@gmail.com>
220     Devraj Mehta <devm33@gmail.com>
221     Edd Salkield <edd@salkield.uk>
222     Eric Collins <eric@tabfugni.cc>
223     Florian Tham <fgtham@gmail.com>
224     George Brocklehurst <george@thoughtbot.com>
225     Graham Bennett <graham@simulcra.org>
226     Jarkko Kniivilä <jkniiv@gmail.com>
227     Jason Daniel Augustine Gilliland <jdagilliland@gmail.com>
228     Javier López <linux.kitten@gmail.com>
229     Joe Ferris <jferris@thoughtbot.com>
230     John Axel Eriksson <john@insane.se>
231     Jordan Eldredge <jordaneldredge@gmail.com>
232     Leonardo Brondani Schenkel <leonardo@schenkel.net>
233     Martin Frost <frost@ceri.se>
234     Mat M <matm@gmx.fr>
235     Matthew Horan <matt@matthoran.com>
236     Melissa Xie <melissa@thoughtbot.com>
237     Michael Reed <supertron421@gmail.com>
238     Mike Burns <mburns@thoughtbot.com>
239     Mike Burns and Eric Collins <mburns@thoughtbot.com>
240     Nick Novitski <github@nicknovitski.com>
241     Pablo Olmos de Aguilera Corradini <pablo@glatelier.org>
242     Patrick Brisbin <pat@thoughtbot.com>
243     Rafael Santos <formigarafa@gmail.com>
244     Rebecca Meritz <rebecca@meritz.com>
245     Roberto Pedroso <roberto@rpedroso.com>
246     Scott Stevenson <scott@stevenson.io>
247     Stephen <stephengroat@users.noreply.github.com>
248     Teo Ljungberg <teo@teoljungberg.com>
249     Tyson Gach <tyson@tysongach.com>
250     Vlad GURDIGA <gurdiga@gmail.com>
251     Yota Toyama <raviqqe@gmail.com>
252     Zach Latta <zach@zachlatta.com>
253     ivan tkachenko <me@ratijas.tk>
254     kajisha <kajisha@gmail.com>
255     maxice8 <thinkabit.ukim@gmail.com>
256     subpop <subpop@users.noreply.github.com>
257     wplatter-cb <39812934+wplatter-cb@users.noreply.github.com>
258
259BSD                              July 28, 2013                             BSD
Impressum