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
72 removed 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
105 example, ~/.zshrc will be a symlink to ~/.dotfiles/zshrc.
106
108 This suite becomes more powerful if you share your dotfiles directory
109 between computers, either because multiple people share the same direc‐
110 tory 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.
163 Instead of running a command such as ln(1) or rm(1), it will print the
164 command 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-
171 install) 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.se
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 Andrei Dziahel <develop7@develop7.info>
205 Anton Ilin <anton@ilin.dn.ua>
206 Ben Stephens <BKStephens@outlook.com>
207 Ben Turrubiates <ben@turrubiat.es>
208 Blake Williams <blake@blakewilliams.me>
209 Caleb Land <caleb@land.fm>
210 Carl van Tonder <carl@supervacuo.com>
211 Casey Rodarmor <casey@rodarmor.com>
212 Christian Höltje <docwhat@gerf.org>
213 Christian Höltje <docwhat@gerf.org>
214 Christopher Koch <ckoch@cs.nmt.edu>
215 Dan Croak <dan@thoughtbot.com>
216 Daniel Watson <dwatson@thig.com>
217 David Alexander <davidpaulalexander@gmail.com>
218 Devraj Mehta <devm33@gmail.com>
219 Edd Salkield <edd@salkield.uk>
220 Eric Collins <eric@tabfugni.cc>
221 Florian Tham <fgtham@gmail.com>
222 George Brocklehurst <george@thoughtbot.com>
223 Graham Bennett <graham@simulcra.org>
224 Jarkko Kniivilä <jkniiv@gmail.com>
225 Jason Daniel Augustine Gilliland <jdagilliland@gmail.com>
226 Javier López <linux.kitten@gmail.com>
227 Joe Ferris <jferris@thoughtbot.com>
228 John Axel Eriksson <john@insane.se>
229 Jordan Eldredge <jordaneldredge@gmail.com>
230 Leonardo Brondani Schenkel <leonardo@schenkel.net>
231 Martin Frost <frost@ceri.se>
232 Mat M <matm@gmx.fr>
233 Matthew Horan <matt@matthoran.com>
234 Melissa Xie <melissa@thoughtbot.com>
235 Michael Reed <supertron421@gmail.com>
236 Mike Burns <mburns@thoughtbot.com>
237 Mike Burns and Eric Collins <mburns@thoughtbot.com>
238 Nick Novitski <github@nicknovitski.com>
239 Pablo Olmos de Aguilera Corradini <pablo@glatelier.org>
240 Patrick Brisbin <pat@thoughtbot.com>
241 Rafael Santos <formigarafa@gmail.com>
242 Rebecca Meritz <rebecca@meritz.com>
243 Roberto Pedroso <roberto@rpedroso.com>
244 Scott Stevenson <scott@stevenson.io>
245 Stephen <stephengroat@users.noreply.github.com>
246 Teo Ljungberg <teo@teoljungberg.com>
247 Tyson Gach <tyson@tysongach.com>
248 Vlad GURDIGA <gurdiga@gmail.com>
249 Yota Toyama <raviqqe@gmail.com>
250 Zach Latta <zach@zachlatta.com>
251 kajisha <kajisha@gmail.com>
252 maxice8 <thinkabit.ukim@gmail.com>
253 subpop <subpop@users.noreply.github.com>
254 wplatter-cb <39812934+wplatter-cb@users.noreply.github.com>
255BSD July 28, 2013 BSD