polk

Dotfile manager.

Installation

With Cargo

cargo install polk

Examples

General usage

# Grab and symlink dotfiles from my GitHub account.
# (assumes repository named 'dotfiles')
polk setup github:dylanmckay

# Grab and symlink dotfiles from another repository.
polk setup github:dylanmckay/otherdotfiles

Multiple users/dotfile repositories

# Set up dotfiles for the default user (with what your computer username is).
# Also symlink them to ~/
polk setup github:dylanmckay

# Download dotfiles to a local cache folder but don't create symlinks
polk grab --user bob github:bob67

# Open a shell to a custom home folder with dotfiles symlinked.
polk shell --user bob

# Create symlinks to the currently grabbed dotfiles
# Replace symlinks in ~/ with what bob has
polk link --user bob

# Update the dotfiles (via git)
polk update

# Remove all symlinks created by polk.
polk unlink

Utilities

# Remove all symlinks and cached dotfiles/repositories (~/.polk)
polk forget

# Print a bunch of information
polk info

Your dotfiles repository

A repository would generally look something like this

.
..
.bashrc
.rspec
.tmux.conf
.tmux.linux.conf
.vim
.config/awesome/config.lua
README.md

How symlinking works works

Here is a table of how dotfiles within a repository map to symlinks in $HOME.

File	Symlink
.bashrc	~/.bashrc -> ~/<dotfiles repository path>/.bashrc
.tmux.conf	~/.tmux.conf -> ~/<dotfiles repository path>/.tmux.conf
.config/awesome/config.lua	~/.config/awesome/config.lua -> ~/<dotfiles repository path>/.config/awesome/config.lua

Handling of config files in subdirectories

As you can see in the above table, if a dotfile resides in a subdirectory(s), those directories will get created in $HOME and then a symlink to the dotfile will be created within the subdirectories.

It is not possible with this tool to symlink an entire directory within a dotfiles repository to $HOME. If this were possible, applications would/could write new files into the repository, which isn't good.

Feature flags

Dotfiles can mention required features in their filenames. These dotfiles will be conditionally symlinked depending on the current system.

When a dotfile is linked, all feature flags are substituted with the feature name. For example, linux will become os, x86 will become arch, and unix will become family. Because of this, it is possible to source OS or arch specific dotfiles the same way across all architectures.

Examples

File	Symlink	Note
.tmux.conf	~/.tmux.conf	No feature flags, will always be linked
.tmux.linux.conf	~/.tmux.os.conf	Will only be linked on Linux
.tmux.linux.x86.conf	~/.tmux.os.arch.conf	Will only be linked on x86 Linux