NAME

SYNOPSIS

DESCRIPTION

This suite is useful for committing your rc files to a central repository to share, but it also scales to a more complex situation such as multiple source directories shared between computers with some host-specific or task-specific files.

This guide serves as a tutorial motivating the suite. For a list of quick reference documentation see the SEE ALSO section below.

QUICK START FOR EXISTING DOTFILES DIRECTORIES

1. Dry run with lsrc(1). Look for anything unexpected in here, such as ~/.install or ~/.Makefile, or an empty list of dotfiles.
   lsrc
2. Update any symlinks with rcup(1). This is likely to do nothing, since your dotfiles already exist.
   rcup -v
3. When necessary, add new rc files to the dotfiles directory with mkrc(1).
   mkrc ~/.tigrc

   In the other direction, you can use rcup(1) to create the symlinks from ~/.dotfiles to your home directory.

   rcup tigrc

QUICK START FOR EMPTY DOTFILES DIRECTORIES

1. Add your rc files to a dotfiles directory with mkrc(1).
   mkrc .zshrc .gitconfig .tigrc
2. Synchronize your home directory with rcup(1)
   rcup -v

This will give you a directory named ~/.dotfiles with your dotfiles in it. Your original dotfiles will be symlinks into this directory. For example, ~/.zshrc will be a symlink to ~/.dotfiles/zshrc.

TAGGED DOTFILES

If you share the dotfiles directory between people, you may end up with some irrelevant or even incorrect rc files. For example, you may have a .zshrc while your other contributor has a .bashrc. This situation can be handled with tags.

1. A tag is a directory under the dotfiles directory that starts with the letters tag-. We can handle the competing shell example by making a tag-zsh directory and moving the .zshrc file into it using mkrc(1) and passing the -t option.
   mkrc -t zsh .zshrc
2. When updating with rcup(1) you can pass the -t option to include the tags you want. This can also be set in the rcrc(5) configuration file with the TAGS variable.
   rcup -t zsh

MULTIPLE DOTFILE DIRECTORIES

The following rcup invocation will go in sequence through the three dotfiles directories, updating any symlinks as needed. Any overlapping rc files will use the first result, not the last; that is, .dotfiles/vimrc will take precedence over marriage-dotfiles/vimrc.

An exclusion pattern can be tied to a specific dotfiles directory.

HOST-SPECIFIC DOTFILES

If your hostname is difficult to compute, or you otherwise want to use a different hostname, you can use the -B flag.

macOS users should see the BUGS section for more details.

STANDALONE INSTALLATION SCRIPT

Using the above command, you can now run install.sh to install (or re-install) your rc files. The install.sh script can be stored in your dotfiles directory, copied between computers, and so on.

RATIONALE

As such, this suite is useful as a common base. Through this we can share tools and develop this further as a first-class entity. It is also our hope that a common set of tools will encourage others to share their dotfiles, too.

FILES

SEE ALSO

AUTHORS

BUGS

CONTRIBUTORS