RCUP(1)

💖 RCUP(1) — the group chat edition 💖

okay bestie, gather round, because this is rcup from the General Commands Manual, and she is that girl. she updates and installs the dotfiles you've been hoarding in your separate dotfiles directory. the whole point: you keep your precious configs in their own little folder, and rcup yeets them into place from your dotfiles directories, or from the host- or tag-specific subfolders inside them. ✨

wanna know the layout? scroll to “DIRECTORY LAYOUT” below, it's all there, no cap.

---

✨ SYNOPSIS ✨

rcup [-CfhiKkqVv] [-B hostname] [-d dir] [-g] [-I excl_pat]
     [-S excl_pat] [-s excl_pat] [-t tag] [-U excl_pat] [-u excl_pat]
     [-x excl_pat] [files ...]

---

🫶 DESCRIPTION 🫶

this is the program that updates and installs your personal dotfiles, and those dotfiles live in their own separate directory. use rcup to install files from your dotfiles directories, or from the host- or tag-specific directories hanging out inside them. 💅

want the full tea on how the folders are arranged? it's in “DIRECTORY LAYOUT”, go look.

she supports these options, and yes we're going through all of them, no skipping:

• -B HOSTNAME — treat host-HOSTNAME as the host-specific directory instead of computing it yourself. let her do the math, it's fine.
• -C — copy the files instead of symlinking them.
• -d DIR — install dotfiles from the DIR. and you can say this one multiple times, she can handle it. 💪
• -f — if the rc file is already sitting in your home directory but it does not match the file in your dotfiles directory, remove the rc file and then create the symlink. out with the old, in with the slay.
• -g — print to stdout a standalone shell script that will run the rcup command as specified. and here's the iconic part: nothing on your filesystem will be modified by rcup when this flag is passed. window shopping only, bestie. 👑
• -h — show usage instructions.
• -I EXCL_PAT — install rc files that match EXCL_PAT even though they got excluded by the -x flag or by a setting in rcrc(5). can be repeated with additional patterns. check lsrc(1), “EXCLUDE PATTERN”, for more details.
• -i — if the rc file already exists in your home directory but doesn't match the file in your dotfiles directory, prompt for how to handle it. this is the default. she'll always ask first, consent queen. 🎀
• -K — skip pre- and post-hooks.
• -k — run pre- and post-hooks (peep “DIRECTORY LAYOUT” for the hook deets). this is the default.
• -S EXCL_PAT — any rc file that matches EXCL_PAT is installed using a symlink even if it's a directory. repeatable, go off.
• -s EXCL_PAT — any file that matches EXCL_PAT is installed as normal, in accordance with the “ALGORITHM” section below. this is the opposite of -S. repeatable, obviously.
• -t TAG — install dotfiles according to TAG.
• -U EXCL_PAT — any rc file that matches EXCL_PAT is installed without a leading dot. repeatable. see the documentation of the -U option in lsrc(1) for more info.
• -u EXCL_PAT — any rc file that matches EXCL_PAT is installed with a leading dot. this is the opposite of -U. repeatable. and it's the default. see the documentation of the -u option in lsrc(1) for more info.
• -q — decrease verbosity. shhh. 🤫
• -V — show the version number.
• -v — increase verbosity. repeat it for extra verbosity. and heads up: verbose messages are printed to stderr. 📢
• -x EXCL_PAT — do not install rc files that match EXCL_PAT. repeatable with additional patterns. see lsrc(1), “EXCLUDE PATTERN”, for more details.
• files — only install the specified file(s). picky, love that for you.

---

🦋 DIRECTORY LAYOUT 🦋

any non-dot, non-meta file or directory under your dotfiles directory gets installed as a dotfile. for example, .dotfiles/zshrc will be installed into ~/.zshrc. cute, right?

files are installed as symlinks. directories are installed by making directories. the -C flag makes files install as copies instead of symlinks. and the COPY_ALWAYS option in rcrc(5) lets you list files that must only be copied. important: copied files are not updated in your dotfiles directory. so like, don't expect them to sync back, that's not the vibe.

three meta files are supported: host-specific files, tagged files, and hooks.

Host-specific files go in a directory named for the host, prefixed with host-. for example, .dotfiles/host-scarlett contains files specific to the computer with hostname scarlett, and those files will only be installed on the computer with hostname scarlett. exclusive. 💅

Tagged files go in a directory named for the tag, prefixed with tag-. so files under .dotfiles/tag-git are only installed when you install using the git tag.

Hooks go in a directory named hooks. rcup supports two hooks: pre-up and post-up. these live in files or directories with predictable filenames: .dotfiles/hooks/pre-up and .dotfiles/hooks/post-up, or .dotfiles/hooks/pre-up/* and .dotfiles/hooks/post-up/*. these files must be executable. they run every single time rcup is run, which means they must be idempotent. no cap, if your hook isn't idempotent you're gonna have a bad time. 😭

hooks get executed one at a time, sorted alphabetically. for instance, hooks/pre-up/animals will run before hooks/pre-up/aquariums, and hooks/pre-up/4-eyes will run before hooks/post-up/2-u-nothing-compares. alphabetical, periodt.

---

🌈 ALGORITHM 🌈

ngl, it's genuinely useful to understand the process rcup uses when synchronizing your rc files. here's the whole storyline:

1. the pre-up hook is run.
2. all non-host, non-tag files without a dot prefix are symlinked to the dotted filename in your home directory. so, .dotfiles/tigrc is symlinked to ~/.tigrc.
3. all non-host, non-tag directories have their structure copied to your home directory, then a non-dotted symlink is created within. so for example, .dotfiles/vim/autoload/haskell.vim causes the ~/.vim/autoload directory to be created, then haskell.vim is symlinked within.
4. steps (2) and (3) are applied to host-specific files. these are files under a directory named host-$HOSTNAME.
5. steps (2) and (3) are applied to tag-specific files. these are files under directories named tag-$TAG_NAME, where $TAG_NAME is the name of each specified tag in turn, taken from the command line or from rcrc(5).
6. the post-up hook is run.

and that's the whole arc, bestie. beginning to end. 🧚

---

🌸 ENVIRONMENT 🌸

• RCRC — user configuration file. defaults to ~/.rcrc.

---

💜 FILES 💜

• ~/.dotfiles
• ~/.rcrc

---

👑 SEE ALSO 👑

lsrc(1), mkrc(1), rcdn(1), rcrc(5), rcm(7)

---

⭐ AUTHORS ⭐

rcup is maintained by Mike Burns <mburns@thoughtbot.com> and thoughtbot: http://thoughtbot.com

---

okay that's the whole page, you ate it, you understood it, main character energy fr fr. 💖

this edition came from Debian, dated July 28, 2013 — so yeah, she's been iconic since way back, and she still slays. byeee 🎀✨