1RCUP(1) BSD General Commands Manual RCUP(1)
2
4 rcup — update and install dotfiles managed by rcm
5
7 rcup [-CfhiKkqVv] [-B hostname] [-d dir] [-g] [-I excl_pat] [-S excl_pat]
8 [-s excl_pat] [-t tag] [-U excl_pat] [-u excl_pat] [-x excl_pat]
9 [files ...]
10
12 This is a program to update and install personal dotfiles. These dotfiles
13 are managed in a separate directory. Use rcup to install files from your
14 dotfiles directories or from host- or tag-specific directories within.
15 See DIRECTORY LAYOUT for details on the directory layout.
17 It supports these options:
19 -B HOSTNAME treat host-HOSTNAME as the host-specific directory instead
21 of computing it.
22 -C copy the files instead of symlinking them.
24 -d DIR install dotfiles from the DIR. This can be specified multi‐
26 ple times.
27 -f if the rc file already exists in your home directory but
29 does not match the file in your dotfiles directory, remove
30 the rc file then create the symlink.
31 -g print to stdout a standalone shell script that will run the
33 rcup command as specified. Nothing on your filesystem will
34 be modified by rcup when this flag is passed.
35 -h show usage instructions.
37 -I EXCL_PAT install rc files that match EXCL_PAT despite being excluded
39 by the -x flag or a setting in rcrc(5). This can be re‐
40 peated with additional patterns. See lsrc(1), EXCLUDE
41 PATTERN, for more details.
42 -i if the rc file already exists in your home directory but
44 does not match the file in your dotfiles directory, prompt
45 for how to handle it. This is the default.
46 -K skip pre- and post-hooks.
48 -k run pre- and post-hooks (see DIRECTORY LAYOUT for more de‐
50 tails on hooks). This is the default.
51 -S EXCL_PAT any rc file that matches EXCL_PAT is installed using a sym‐
53 link even if it is a directory. This option can be repeated.
54 -s EXCL_PAT any file that matches EXCL_PAT is installed as normal, in
56 accordance with the ALGORITHM section below. This is the op‐
57 posite of -S. This option can be repeated.
58 -t TAG install dotfiles according to TAG.
60 -U EXCL_PAT any rc file that matches EXCL_PAT is installed without a
62 leading dot. This option can be repeated. See the documenta‐
63 tion of the -U option in lsrc(1) for more information.
64 -u EXCL_PAT any rc file that matches EXCL_PAT is installed with a lead‐
66 ing dot. This is the opposite of -U. This option can be re‐
67 peated. This is the default. See the documentation of the -u
68 option in lsrc(1) for more information.
69 -q decrease verbosity.
71 -V show the version number.
73 -v increase verbosity. This can be repeated for extra ver‐
75 bosity. Verbose messages are printed to stderr.
76 -x EXCL_PAT do not install rc files that match EXCL_PAT. This can be
78 repeated with additional patterns. See lsrc(1), EXCLUDE
79 PATTERN, for more details.
80 files only install the specified file(s)
82
84 Any non-dot non-meta file or directory under your dotfiles directory will
85 be installed as a dotfile. For example, .dotfiles/zshrc will be installed
86 into ~/.zshrc .
87 Files are installed as symlinks. Directories are installed by making di‐
89 rectories. The -C flag causes files to be installed as copies instead of
90 symlinks. The COPY_ALWAYS option in rcrc(5) can be used to list files
91 that must only be copied. Copied files are not updated in your dotfiles
92 directory.
93 Three meta files are supported: host-specific files, tagged files, hooks.
95 Host-specific files go in a directory named for the host, prefixed with
97 host-. For example, .dotfiles/host-scarlett contains files specific to
98 the computer with hostname scarlett, and these files will only be in‐
99 stalled on the computer with hostname scarlett.
100 Tagged files go in a directory named for the tag, prefixed with tag-.
102 Therefore, files under .dotfiles/tag-git are only installed when in‐
103 stalling using the git tag.
104 Hooks go in a directory named hooks. Two hooks are supported by rcup:
106 pre-up and post-up. These go in files or directories with predictable
107 filenames: .dotfiles/hooks/pre-up and .dotfiles/hooks/post-up, or
108 .dotfiles/hooks/pre-up/* and .dotfiles/hooks/post-up/*. These files must
109 be executable. They are run every time rcup is run, and therefore must be
110 idempotent.
111 Hooks will be executed one at a time, sorted alphabetically. For in‐
113 stance, hooks/pre-up/animals will run before hooks/pre-up/aquariums, and
114 hooks/pre-up/4-eyes will run before hooks/post-up/2-u-nothing-compares.
115
117 It is instructive to understand the process rcup uses when synchronizing
118 your rc files:
119 1. The pre-up hook is run.
121 2. All non-host, non-tag files without a dot prefix are symlinked to
123 the dotted filename in your home directory. So, .dotfiles/tigrc is
124 symlinked to ~/.tigrc.
125 3. All non-host, non-tag directories have their structure copied to
127 your home directory, then a non-dotted symlink is created within.
128 So for example, .dotfiles/vim/autoload/haskell.vim causes the
129 ~/.vim/autoload directory to be created, then haskell.vim is sym‐
130 linked within.
131 4. Steps (2) and (3) are applied to host-specific files. These are
133 files under a directory named host-$HOSTNAME.
134 5. Steps (2) and (3) are applied to tag-specific files. These are files
136 under directories named tag-$TAG_NAME, where $TAG_NAME is the name
137 of each specified tag in turn, taken from the command line or from
138 rcrc(5).
139 6. The post-up hook is run.
141
143 RCRC User configuration file. Defaults to ~/.rcrc.
144
146 ~/.dotfiles ~/.rcrc
147
149 lsrc(1), mkrc(1), rcdn(1), rcrc(5), rcm(7)
150
152 rcup is maintained by Mike Burns <mburns@thoughtbot.com> and thoughtbot:
153 http://thoughtbot.com
154BSD July 28, 2013 BSD