1RCM(7) BSD Miscellaneous Information Manual RCM(7)
2
4 rcm — dotfile management
5
7 lsrc
8 mkrc
9 rcdn
10 rcup
11
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 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 This guide serves as a tutorial motivating the suite. For a list of quick
25 reference documentation see the SEE ALSO section below.
26
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 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 lsrc
37 2. Update any symlinks with rcup(1). This is likely to do nothing,
39 since your dotfiles already exist.
40 rcup -v
42 3. When necessary, add new rc files to the dotfiles directory with
44 mkrc(1).
45 mkrc ~/.tigrc
47 In the other direction, you can use rcup(1) to create the symlinks
49 from ~/.dotfiles to your home directory.
50 rcup tigrc
52 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 rcup -x install -x Rakefile -x Makefile -x install.sh
60 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 find ~/.dotfiles -name '.*' -exec echo mv {} `echo {} | sed
69 's/.//'` ;
70 Note that this will break any existing symlinks. Those can be safely re‐
72 moved using the rcdn(1) command.
73 rcdn -v
75 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 rcup -d configs -v
82 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 mkrc -U bin
90
92 This section is for those who do not have an existing dotfiles directory
93 and whose dotfiles are standard.
94 1. Add your rc files to a dotfiles directory with mkrc(1).
96 mkrc .zshrc .gitconfig .tigrc
98 2. Synchronize your home directory with rcup(1)
100 rcup -v
102 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
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 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 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 mkrc -t zsh .zshrc
123 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 rcup -t zsh
129
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 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 rcup -d .dotfiles -d marriage-dotfiles -d thoughtbot-dotfiles
141 An exclusion pattern can be tied to a specific dotfiles directory.
143 rcup -d .dotfiles -d work-dotfiles -x 'work-dotfiles:powrc'
145
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 mkrc -o .rcrc
153 If your hostname is difficult to compute, or you otherwise want to use a
155 different hostname, you can use the -B flag.
156 mkrc -B eggplant .rcrc
158 macOS users should see the BUGS section for more details.
160
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 env RCRC=/dev/null rcup -B 0 -g > install.sh
169 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
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 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
186 ~/.dotfiles ~/.rcrc
187
189 lsrc(1), mkrc(1), rcdn(1), rcup(1), rcrc(5)
190
192 rcm is maintained by Mike Burns <mburns@thoughtbot.com> and thoughtbot:
193 http://thoughtbot.com
194
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
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>
258BSD July 28, 2013 BSD