Homely - Dotfile Management

One of the joys of being a software developer is meticulously customising the various tools you use such that you maximise their utility and potential for your own personal needs. These customisations are typically stored in files with names that begin with a dot (“.”), so developers have creatively named them “Dotfiles”.

One of the great frustrations as a software developer is jumping onto a different computer and having none of your customisations available. Many developers have taken to storing their Dotfiles in a git repository so that changes can be shared across computers easily, and then added shell scripts to automate their installation. However, the lack of programming features available in shell scripts soon becomes a dreadful burden as you continue to add more and more customisations to your shell script.

homely is a small tool which allows you to take a repository full of Dotfiles and script their installation using a real programming language (Python). It provides a small library containing the sorts of functions you need to programmatically write Dotfiles and install software packages, and a simple CLI tool to make running your installation script easy.

If you want to use homely to manage your dotfiles, you will need to be able to:

  1. Commit your dotfiles to one or more git repos which are hosted online (publically or privately is fine).
  2. Write a small python script which tells homely how to install each of your dotfiles.

For example, you might put all of your dotfiles into a git repo that looks like this:

[peter@yourpc] /Users/peter/dotfiles [master]$ ls -a
.              .git            .screenrc
..             .gitconfig      .tmux.conf
.ackrc         .hgrc           .vimrc
.bashrc        .isort.cfg

Then, you could write a small HOMELY.py script to symlink each of these files into your home directory:

$ cat ~/dotfiles/HOMELY.py
from homely.files import symlink
symlink('.ackrc')
symlink('.bashrc')
symlink('.git')
symlink('.gitconfig')
symlink('.hgrc')
symlink('.isort.cfg')
symlink('.screenrc')
symlink('.tmux.conf')
symlink('.vimrc')

Important! If you _only_ want to use symlinks and shell scripts to install your dotfiles on each computer, then there are other mature projects that are better suited for this. You can find a list of them at https://dotfiles.github.io/. The reasons for using homely over other dotfile managers are:

  1. You want the full power of the python programming language at your disposal so that you aren’t limited to just the features of your Dotfile Manager or things that can be done in a shell script.
  2. homely makes a reasonable attempt at cleaning up things you don’t use any more. Removed symlink(".screenrc") from your repo? homely will notice that it’s not being asked for any more and remove the .screenrc symlink on any computer where it was previously installed.

If you would like to learn more, check out the Beginner Tutorial or the Installation Guide.