Dotfiles: Manage Your Development Environment Configuration in GitHub

Disclaimer: This content reflects my personal opinions, not those of any organizations I am or have been affiliated with. Code samples are provided for illustration purposes only, use with caution and test thoroughly before deployment.

Linux is my major development platform. Most of the tool I use (vim, zsh, i3 window manager) use configuration files located in your home directory (.vimrc, .zshrc and .i3/config). It is pretty hard to keep them in sync between your machines. And sometimes if you mess up with the configuration file it’s pretty hard to revert your changes.

One day when I was looking for some vim configuration inspirations on GitHub, I stumbled upon a repository called “dotfiles” (I forgot whos repository it was), which contains all the configuration files in one repository. (In case you don’t know, It’s called “dotfiles” because most of the configuration filename start with a . so they are hidden.) This is actually a brilliant idea, by saveing your configuration files in a git repository, you get all the version control goodies. This aligns (kind of) with the DevOps concept of “infrastructure as code”. I would call it “development environment as code”.

There are many benefits of doing so. First, you can easily setup new machines by cloning the repository. Secondly, you have a full version control history of your configuration files, which makes it easy to revert changes or bisecting configuration errors. You can go back to a known good state when you mess everything up. You can also use git branches to manage machine specific settings. For example, you might want to have some special configurations in your office computers, which makes no sense in your home computer. In such situation you create two branches, one for your office machine and one for your home machine. You can still share common configurations between the two branches, while you keep the machine-specific part apart. Last but not least, by publishing your configuration files on GitHub, you can easily shared them with your friends.

Step-by-step Guide

Here are the exact steps to implement this method:

1. Create a folder called dotfiles in your home directory.

    cd ~
    mkdir dotfiles
   

2. Copy all you configuration files into the folder.

    cp .vimrc dotfiles/vimrc # Remove the dot so its no longer hidden
    cp .zshrc dotfiles/zshrc
    cp .i3/config dotfiles/i3config
   

3. Remove the original configuration files, put softlinks in-place and point them to the files in the dotfiles folder.

    rm .vimrc 
    rm .zshrc
    rm .i3/config 
   
    ln -s dotfiles/vimrc .vimrc
    ln -s dotfiles/zshrc .zshrc
    ln -s dotfiles/i3config .i3/config
   

4. Init a git repo, then add, commit and push your configuration files to GitHub. (Remember to remove any sensitive data like passwords, API tokens, personal information before you push.)

    cd dotfiles
    git init
    git add .
    git commit -m "Added my vimrc, zshrc and i3 config"
    # Setup your GitHub remote here
    git push 
   

5. When you have a new computer you need to setup, git clone the repository and run the ln -s ... lines. Or you can put those lines in a shell script for one-click installation.

Tips

• You can use the master branch as the template branch. When you have settings that applies to all platform, put them in the master branch. Then in all other machine-specific branches, merge or cherry pick the change from the master branch.
• I love to write little utility scripts in shell script or Python. For example I have a shell script that temporarily disable the screensaver when I watch movies. I put those utility scrips in the repository too.
• You may also consider saving your Linux package lists in the repository. You can then create a shell script that install all of them in one click. This helps you setup the exact same development environment in any new computer. You can use the following command to see what package you have installed on your current computer.

aptitude search '~i !~M' -F '%p' --disable-columns

(I use Debian-based Linux, but you can probably find similar command for other OS and package manager.)

Further Reading

• Here is my dotfiles repository. It’s quite messy and I clearly doesn’t practice all the things I preach.
• You can find a lot of dotfiles repositories on GitHub