Intro to Dotfiles

In this weeks episode, Chris & Gabe dive into the world of dotfiles, the files we use to configure some of our favorite tools. Tune in to find out how Chris, Gabe, and thoughtbot think about and organize these critical files.

Introduction

Dotfiles are plain text configuration files on Unix-y systems for things like our shell, ~/.zshrc, our editor in ~/.vimrc, and many others. They are called "dotfiles" as they typically are named with a leading . making them hidden files on your system, although this is not a strict requirement.

Since these files are all plain text, we can gather them together in a git repository and use that to track the changes you make over time.

thoughtbot dotfiles

The thoughtbot dotfiles are a shared repository used by many of the developers at thoughtbot. They are purposefully somewhat limited in how far they go with configuration and customization as they are intended to be used as a base.

Local Overrides

Each of the config files in the thoughtbot dotfiles provides a base configuration but will also read in a "local" file to allow for additional, more personalized configuration.

For example, thoughtbot's dotfiles contain a ~/.vimrc file will the base that will optionally source in a ~/.vimrc.local file if available. You can use this ~/.vimrc.local file to override and add to the configurations provided by the base ~/.vimrc file.

rcm dotfile management utility

The thoughtbot dotfiles use a utility called rcm, written by a collection of thoughtbotters, that automates the management and linking of the various individual files from their homes in the repos, to the expected locations in your home directory.

Even if you're not using the thoughtbot dotfiles, rcm is a great tool for managing your own dotfile setup.

Distributed Dotfile Convention

One approach both Gabe and Chris take is to break apart the otherwise very large config files into smaller, more manageable config files:

• Gabe's vimrc references all the other Vim config files he has, which are themselves stored elsewhere in his Vim configuration.
• Similarly, his zshrc sources in all the other zsh config files he has.
• A particular case is Gabe's vundle.vim file which contains the plugin list used by Vundle to manage all of his plugins.

This has the benefit of allowing for a bit more structure and organization of these config files than would otherwise be the case if all the configuration were in a single file.

Note - Be sure to checkout the Onramp to Vim trail to level up your Vim game, especially the videos on Configuration and Plugins.

Vim Filetype Configuration

There are a few special directories that Vim will look in to define specific configurations.

• ftdetect - If you have files in an ~/.vim/ftdetect folder, Vim will automatically run those files every time a new file is opened to allow you to dynamically detect and set the filetype. This is useful for files like markdown (*.md) which Vim would otherwise mistakenly treat as "modula2" files.
• ftplugin - The files in this directory will be run based on their filename for a given filetype. For instance, a ~/.vim/ftplugin/markdown.vim config file will be run for all markdown files. This allows for filetype specific configurations.

Zsh Configuration

Similar to Vundle for Vim, there is Antigen for zsh which acts as a plugin downloader and manager for zsh. It can target anything in oh-my-zsh allowing to pick and choose specific pieces without needing to install the full oh-my-zsh.

Git Configuration

Aliases

Git allows you to define custom aliases that run just like git commands. These are stored in your ~/.gitconfig file in the aliases section and can be defined by either directly editing that file, or running a command like:

# Create a git alias, runnable as `git unstage` to unstage files.
$ git config --global alias.unstage 'reset HEAD --'

Scripts

Git will automatically run any script that matches the subcommand name which allows you to create more complex git commands yourself. For example, if you run git newbranch, git will look on your PATH for any script called git-newbranch and will execute it if found.

Fall through g Alias

The thoughtbot dotfiles (as well as Chris, Gabe's, Ben's, pretty much everybody's) contain a useful shell alias that makes interacting with git much easier. You can view the alias on github in the thoughtbot dotfiles, and we've included it below as well:

# No arguments: `git status`
# With arguments: acts like `git`
g() {
  if [[ $# > 0 ]]; then
    git $@
  else
    git status
  fi
}

# Complete go like git
compdef g=git

The alias is g and can be run with or without arguments:

• Without Arugments - Running just g in the shell will run git status
• With Arguments - The arguments / command are passed through to git, so running g merge - is the same as running git merge -.

This may not seem like a lot, but when you consider how much you use git every day, each of those 2 character savings (9 in the case of bare g!) adds up.

Dotfiles Philosophy

The following are some guidelines that we recommend. These are, of course, not hard and fast rules, but instead rules of thumb that you would likely want to follow unless you have a specific reason not to.

Avoid automation

While this may sound heretical in a video about dotfiles, we actually recommend not jumping to automate and configure too quickly. All automation has a cost (maintenance, initial setup and tweaking time, etc) so be wary of automating too quickly.

Rule of 3

Chris employs a rule of 3 to determine when to automate. If he feels the same annoyance or friction 3 times in recent memory, then the time has come to automate.

Use Time Boxed Spikes

Once something hits the magic 3 annoyance count, give yourself a short (5-10 minutes) boxed window of time to take a stab at a first solution. When you are in context feeling the friction you often are in the best place to solve something that might otherwise never be handled.

Capture Notes

Chris uses his dotfiles repo issues as a place to track bigger problems or updates he'd like to tackle. This has a number of benefits:

1. Capture annoyances that would take too much time to solve.
2. Allow some time to pass to make sure this annoyance is truly worth fixing
3. Capture any work you've done thus far. Maybe you were able to get a partial solution in your 5-10 minute time box. Save off what you have so you can come back when you have more time
4. Allow the future, smarter you to solve this problem. You may not have the knowledge to solve a particular problem when you first encounter it, but down the road you might!

Share Your Dotfiles

Nearly all dotfiles repos are a collection of bits borrowed or copied from others, so it only makes sense to share yours back. This is as easy as sharing them as a public repo on Github. Dotfiles are meant for sharing after all.

Don't Use Someone Else's Dotfiles

In general, dotfiles end up being extremely specific to an individual developers workflows and preferences. As such, it's probably not a great idea to grab those and run with them.

One particular case where this is not true is the thoughtbot dotfiles. These are specifically designed to provide a minimal (but highly useful and curated!) foundation which you are then expected to layer your more specific configurations and preferences on top of.

Levelling Up Your Dotfiles

One great way to level up your dotfiles knowledge is just to watch another user's dotfiles and see what sort of things they are doing.

In addition, remember that dotfiles are a long game, something that you're constantly going to be tweaking, updating, and refining rather then finishing in a long weekend.

That said, there are a few resources we'd recommend for learning more about configuring specific tools:

• Our own Onramp to Vim trail on Upcase
• Learn Vimscript the Hard Way
• Git Ready - Great collection of answers to "how do I do X in git"
• Our Tmux Course here on Upcase