Sync dotfiles with GitHub

What are dotfiles?

The term dotfiles refers to configuration files for various Linux or OSX utilities, primarily command line applications, which reside in your home directory and begin with a period character. Examples are .vimrc for Vim and .bashrc for Bash.

Some programs have hundreds of options, granting a multitude of permutations on form and function. For example, you can change your color scheme, or automate a common task with a shortcut.

It’s common for software engineers to maintain a set of these dotfiles and evolve them over the course of their career. Eventually, they may end up with interfaces that are hyper optimized just for them.

Why host them on version control?

Hosting your dotfiles on a site like GitHub has several advantages. Centralization means you can easily sync your configuration between any number of machines that you use regularly. Having them publicly available means that you can easily share them with other developers. Versioning them makes it easy to roll back a recent change.

How you can use GitHub to sync dotfiles

If you simply maintain a shared folder of configuration files, whether it’s on GitHub or Dropbox, you will quickly run into an irksome maintenance problem every time you need to provision a new machine, or update an exiting one. Because these configuration files need to be located in your home directly to take effect, you will end up manually copying or maybe sym-linking them one at a time.

You might think to write a script for this. No need! There are plenty of exiting utilities out there that do just this. As a Python developer, I choose to use a utility on pip called simply dotfiles.

I encourage you to read the documentation, but essentially this tool maintaines a single directory with a master copy of all your configuration options, and syncs them into the correct place on demand. This should be enough to get you started:

pip install dotfiles
dotfiles --add ~/.vimrc
cd ~/Dotfiles
git init
git add vimrc  # notice that the canonical version does not start with a dot
git commit -m "Added vimrc, welcome aboard!"

From then on, you can git push your changes to your GitHub account. When you want to sync your dotfiles to a new machine, just do a git clone and then run dotfiles --sync.

Gotchas

I did not personally like the default ~/Dotfiles directory. Instead, I used ~/.dotfiles, which you can specify in your .dotfilesrc.

I also ended up using the configuration options for ignores and packages. The later symlinks entire configuration directories, like ~/.ssh.

Note: do not check your SSH private key into a public repository!

Some gems from my personal dotfiles

My most extensive configuration is my vimrc. Check it out; it’s pretty well commented. I especially like the python-mode integration, for features like jumping into the definitions of other modules, and doing in-editor linting.

I have an install.sh script, which contains different blocks for various platforms:

unamestr=`uname`
if [[ $unamestr == 'Linux' ]]; then
    ...
elif [[ $unamestr == 'Darwin' ]]; then
    ...
fi

I’ve also done some work to enable integration with the OSX clipboard for copying and pasting while inside an SSH session.