---
name: "rcup"
section: "1"
platform: "linux"
package: "rcm"
version: "1.3.4-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/rcup"
---

# rcup(1)

update and install dotfiles managed by rcm

## NAME

**rcup** – update and install dotfiles managed by rcm

## 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 a program to update and install personal dotfiles. These dotfiles are managed in a separate directory. Use **rcup** to install files from your dotfiles directories or from host- or tag-specific directories within.

See DIRECTORY LAYOUT for details on the directory layout.

It supports these options:

- **-B** *HOSTNAME*

  treat *host-HOSTNAME* as the host-specific directory instead of computing it

- **-C**

  copy the files instead of symlinking them

- **-d** *DIR*

  install dotfiles from the *DIR*. This can be specified multiple times.

- **-f**

  if the rc file already exists in your home directory but does not match the file in your dotfiles directory, remove the rc file then create the symlink

- **-g**

  print to stdout a standalone shell script that will run the **rcup** command as specified. Nothing on your filesystem will be modified by **rcup** when this flag is passed.

- **-h**

  show usage instructions.

- **-I** *EXCL\_PAT*

  install rc files that match *EXCL\_PAT* despite being excluded by the **-x** flag or a setting in [rcrc(5)](/rcrc/5.md). This can be repeated with additional patterns. See [lsrc(1)](/lsrc/1.md), EXCLUDE PATTERN, for more details.

- **-i**

  if the rc file already exists in your home directory but does not match the file in your dotfiles directory, prompt for how to handle it. This is the default

- **-K**

  skip pre- and post-hooks

- **-k**

  run pre- and post-hooks (see DIRECTORY LAYOUT for more details on hooks). This is the default.

- **-S** *EXCL\_PAT*

  any rc file that matches *EXCL\_PAT* is installed as if it were a file (using a symlink) instead of as if it were a directory (by making a directory). This option can be repeated.

- **-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**. This option can be repeated.

- **-t** *TAG*

  install dotfiles according to *TAG*

- **-U** *EXCL\_PAT*

  any rc file that matches *EXCL\_PAT* is installed without a leading dot. This option can be repeated. See the documentation of the **-U** option in [lsrc(1)](/lsrc/1.md) for more information.

- **-u** *EXCL\_PAT*

  any rc file that matches *EXCL\_PAT* is installed with a leading dot. This is the opposite of **-U**. This option can be repeated. This is the default. See the documentation of the **-u** option in [lsrc(1)](/lsrc/1.md) for more information.

- **-q**

  decrease verbosity

- **-V**

  show the version number.

- **-v**

  increase verbosity. This can be repeated for extra verbosity. Verbose messages are printed to stderr.

- **-x** *EXCL\_PAT*

  do not install rc files that match *EXCL\_PAT*. This can be repeated with additional patterns. See [lsrc(1)](/lsrc/1.md), EXCLUDE PATTERN, for more details.

- *files*

  only install the specified file(s)

## DIRECTORY LAYOUT

Any non-dot non-meta file or directory under your dotfiles directory will be installed as a dotfile. For example, *.dotfiles/zshrc* will be installed into *~/.zshrc* .

Files are installed as symlinks. Directories are installed by making directories. The **-C** flag causes files to be installed as copies instead of symlinks. The *COPY\_ALWAYS* option in [rcrc(5)](/rcrc/5.md) can be used to list files that must only be copied.

Three meta files are supported: host-specific files, tagged files, 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 these files will only be installed on the computer with hostname *scarlett*.

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

Hooks go in a directory named *hooks*. Two hooks are supported by **rcup**: pre-up and post-up. These go 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 are run every time **rcup** is run, and therefore must be idempotent.

Hooks will be 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*.

## ALGORITHM

It is instructive to understand the process **rcup** uses when synchronizing your rc files:

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)](/rcrc/5.md).

6. The post-up hook is run.

## ENVIRONMENT

- RCRC

  User configuration file. Defaults to *~/.rcrc*.

## FILES

*~/.dotfiles* *~/.rcrc*

## SEE ALSO

[lsrc(1)](/lsrc/1.md), [mkrc(1)](/mkrc/1.md), [rcdn(1)](/rcdn/1.md), [rcrc(5)](/rcrc/5.md), [rcm(7)](/rcm/7.md)

## AUTHORS

**rcup** is maintained by Mike Burns ⟨*mburns@thoughtbot.com*⟩ and *thoughtbot:* **http://thoughtbot.se**