dotfiles

dot

Manage your personal dotfiles with GNU Stow.

GNU Stow can be used directly, but a helper script ./dot is provided to easy the syntax and to support my custom package Target feature.

This is a Linux first design, but there is rudimentry support for Windows.

Windows users should use the ./dot.ps1 script instead of the ./dot script.

As GNU Stow is currently unavailable on Windows, ./park.ps1 provides bare minimum functionality for the ./dot.ps1 Windows implementation.

Usage

Keep your dotfiles in your git repo and symlink them into the correct place, allowing you to edit them without forgetting to copy those changes back into your repo.

Further, you can apply your dotfiles to another system by simply checking out your dotfiles repo and running:

./dot apply <package>

Any existing dotfiles on the system will be left as is. So there is no risk of accidentally clobbering untracked dotfiles.

NOTE: because clobbering existing dotfiles is avoided, you will have to manually delete or move existing config files out of the way. This only applies to files with same name and location as those in your dotfiles repo. Any other unrelated files (even in the same directory) can co-exist just fine.

Your applied config can be cleaned up by running:

./dot remove <package>

This removes the symlinks to your dotfiles that were previously applied effictively wiping your config.

Only symlinks to your config files are created, and only symlinks are removed. Therefore there is no risk of losing any changes you may have made since you applied your config.

Repo Structure

The files here are structured for compatibility with GNU Stow to keep things as simple as possible and reduce reliance on custom logic.

You can package you dotfiles however you like, either by program or a collection of programs.

Packages that require config files in multiple locations are supported, so you don't have to jump through hoops to keep all your config in a single file or directory.

You can optionally apply only part of your config depending on requirements:

./dot apply <package> system

./dot apply <package> user

Packages

A package is simply a collection of dotfiles (or any config file) that should be applied together.

For added flexability, a package may also contain one or more targets.

Package Structrue

All config files for a specific package are kept together in a top level subdirectory of the repo.

The directory structure of each package target is compatible with GNU stow.

A package is therefore simply one of thes top level directories and can consist of a config for one or more programs depending on your needs.

Exampe Repo Structure

When discussing how package targets are handled, the following repo structure will be assumed:

Example with dotfiles repo checked out to ./dotfiles (DOTFILES_DIR):

./dotfiles
├── Readme.md
├── ssh
│   ├── system
│   │   └── etc
│   │       └── ssh
│   │           ├── ssh_config
│   │           └── sshd_config
│   └── user
│       └── .ssh
│           └── config
└── vim
    └── .vimrc

This shows a repo with two packages:

• vim - no targets (so is assumed to be a user target)
• ssh - two targets: system and user

The ./dot Script

There is a custom wrapper bash script (useing GNU Stow) that you can use to easily install a config package:

Example Install the config for the vim package:

./dot apply vim

Or, if the vim package has no other targets, you can use GNU Stow directly:

stow -t "$HOME" vim

Windows users may use the park.ps1 script as GNU Stow

Multiple targets are supported in the case a given package has a mix of user config and system config.

Example Install only system config for the ssh package:

./dot apply ssh system

Example Install all config for the ssh package:

./dot apply ssh

You can still use GNU Stow directly, with just a minor tweak to the stow options to support the multi-target directory structure:

stow -d ssh -t "/" system
stow -d ssh -t "$HOME" user

NOTE: the package name is now passed to stow as the stow directory and the package target is passed as the package name.

Targets

At risk of improving upon the perfection that is GNU Stow, the concept of package targets is added to handle programs that do not store all config in a single location, or for when you want to keep some config separate depending on the target.

For example, you may want to stow your personal and system ssh(d) config on your home computer, but only your personal ssh config on a remote server.

By keeping the system and user config separate (as is typically the case when installed), then you can optionally instruct GNU Stow to apply only one of the targets.

Each package may have files that target the system or the user file heirarchy.

Therefore, each package may have a subdirectory containing any of:

• system
• user

In the case no target subdirectories are present for a given package, then the target is assumed to be the user target.

NOTE: More targets may be added in the future:

• user-config (/home/acme/.config)
• user-local (/home/acme/.local)
• system-opt (/opt)
• system-local (/usr/local)
• system-lib (/usr/local/lib)

But for now, $HOME and / is suffient to cover most use cases whilst keeping the package structure as simple as possible (albeiet with long somewhat redundant paths).

The User Target

All directories under the user target are relative to $HOME.

Example Stow the .vimrc at $HOME:

./dot apply vim

Given the example repo structure, the resulting $HOME dir will look like:

/home/acme
└── .vimrc -> ./path/to/dotfiles/vim/.vimrc

On a GNU Stow compatible system this is equivalent to:

stow -d "$DOTFILES_DIR" -t "/home/$USER" vim

The System Target

All directories under the system targt are relative to /.

Example Stow system/user ssh config at $HOME and / respectively:

./dot apply ssh

Given the example repo structure, the resulting $HOME and / dir will look like:

/home/acme
└── .ssh
    ├── config -> ./path/to/dotfiles/ssh/user/.ssh/config
    ├── id_ecdsa
    ├── id_ecdsa.pub
    └── known_hosts
/etc
└── ssh
    ├── ssh_config -> ./path/to/dotfiles/ssh/system/etc/ssh/ssh_config
    ├── ssh_config.d
    └── sshd_config -> ./path/to/dotfiles/ssh/system/etc/ssh/sshd_config

NOTE: given that one of the ssh package targets is a system target, you will likely need to run ./dot as root. In most cases, this should be fine as the files created will be symlinks, so permissions are not relevant. However, if this is not an option for you, you can apply the user and system targets separately, requiring only running the system target as root.

On GNU Stow compatible system this is equivalent to:

stow -d "$DOTFILES_DIR/ssh" -t "/home/$USER" user
stow -d "$DOTFILES_DIR/ssh" -t / system # needs root permissions obviously

Debug

To see what GNU Stow would do without making any changes, set the DEBUG environment var.

DEBUG=2 ./dot apply vim

The var can be an integer between 1 and 5 to increase verbosity.

Further more, if the DEBUG environment variable is set, then the stow commands being run will be printed - handy if you would prefer to just run stow directly but would like a template to work with.