a tool for managing your ~/dotfile/ symlinks



$  git clone https://github.com/yourself/dotfiles.git
$  cd dotfiles
$  ./deedot
$  ls -l ~/.bashrc
~/.bashrc -> ~/dotfiles/.bashrc

# Your dotfiles are safe.  DeeDot won't overwrite anything.

DeeDot is a tool for installing dotfile symlinks in your $HOME, allowing you to keep your versioned dotfiles under a single directory.

Host your dotfiles in any version control system (eg. Git, Hg, SVN, even rsync), and voila, your dotfiles are available across multiple machines.


Run DeeDot, fix the file conflicts that it notes. Rinse and repeat until it doesn't report any conflicts.

DeeDot recognizes three different ways to incorporate ~/dotfiles/ settings into the working versions in $HOME:

  • Symlink — If you don't want any local-machine overrides. For example, ~/.bashrc can just be a symlink to ~/dotfiles/.bashrc.

  • Source — Some file types have the ability to 'source' another file.

  • Text substitution — DeeDot will read the text from *.subst files, and copy-n-paste it into the middle of the working version.

These are explained below.


For example:

~/.bashrc        -> ~/dotfiles/.bashrc
~/.lesskey       -> ~/dotfiles/.lesskey
~/.tmux.conf     -> ~/dotfiles/.tmux.conf
~/.vimrc         -> ~/dotfiles/.vimrc
~/bin/termdetect -> ~/dotfiles/bin/termdetect
~/bin/rmrf       -> ~/dotfiles/bin/rmrf

Machine-specific overrides — via source

One way to have local machine-specific settings that override the global repository settings is to use the 'source' feature available in some file types. For example, ~/.bashrc can contain:

# Pull in the global settings
[ -f ~/dotfiles/.bashrc ] && source ~/dotfiles/.bashrc

# Override the global settings for this specific machine
export TERM=xtermc

DeeDot knows about each file type, and will suggest the appropriate 'source' line.

Machine-specific overrides — via text substitution

For files that don't have 'source' capability, text substitution is available as a fallback.

For example, DeeDot will update the section of ~/.ssh/config every time it's run:

######## MODIFICATIONS HERE WILL BE OVERWRITTEN BY CONTENTS OF: ~/dotfiles/.ssh/config.subst ########
Host github.com
    User git
    IdentityFile ~/.ssh/github.priv
######## END SUBSTITUTION FROM: ~/dotfiles/.ssh/config.subst ########

Host webstaging.work.com
    User my-username

# ... a bunch of other private stuff that I don't want to make available on the public repository.

DeeDot can also do variable interpolation for environment variables, when in text-substitution mode. For example, in .gitconfig.subst:

    # global gitignore settings
    excludesfile = <<$HOME>>/.gitignore

Minimal requirements

DeeDot requires only Perl, and doesn't need any extra modules. It is designed to run on as many Un*xes as possible. It has been used regularly on various versions of Solaris, AIX, and Linux.

Examples of DeeDot in use

Similar projects

A literature review was done while writing this. The following projects are those that inspired this, or are recommended as alternatives: