Dotfiles for Developers — Part 1

I have spent way too many hours pouring over “dotfiles” repositories on GitHub — hoping to add shortcuts or small improvements to my personal setup.

There are already plenty of resources on the web for managing and configuring your own dotfiles, but I wanted to document my own “best practices” in the hopes that someone else could possibly learn from my experience.

This guide is tailored to developers using macOS and is intended for beginners. However, my hope is that even experienced developers can pick up a few tips & tricks along the way.

Note: Dotfile configuration is extremely personal. This guide outlines my preferences but you should take inspiration from this and other resources and use the pieces that work for you.

What are dotfiles?

If you aren’t familiar with dotfiles, then let’s start here. Dotfiles are small configuration files found on *nix systems that allow you to customize that system based on your own personal preferences. These files usually have names that begin with a . and are thus hidden from standard directory listings.

Sample terminal output showing various dotfiles.

Homebrew

Homebrew is marketed as “the missing package manager for macOS (or Linux)” and has earned its reputation as such. It is essential and is most likely the first thing any developer installs when setting up a new machine.

Homebrew allows you to easily install/update tools and even Applications from your command line interface by running brew install <formula>.

Installation

Before you can install Homebrew, you must have the Command Line Tools for Xcode installed. It includes the compilers and tools necessary to build from source. You can install it by running the following:

sudo xcode-select --install

You can then install Homebrew by running the simple installation command on the Homebrew website:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Setting Up Your $PATH

Your system $PATH is basically just a list of directories (separated by :). When you enter a command into the terminal, your system will go through those directories and look for the program that corresponds to that command.

Homebrew installs tools to /usr/local/bin by default, so you should ensure this directory is near the beginning of your $PATH.

This step is done for you on the latest versions of macOS, but it is essential for the tools installed with Homebrew to function properly. If you are on a version of macOS prior to 10.14 Mojave, run the following command to add the Homebrew installation location to your $PATH:

echo 'PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile

Note: The Homebrew installation and the command above will configure your $PATH for Bash shells. We will be installing Zsh in the next section — and thus, we will need to configure our $PATH there as well.

Alternatively — for advanced users — you can insert /usr/local/bin at the beginning of the file /etc/paths to change the global system default paths order (for all users/shells). The final result should look something like this:

/usr/local/bin
/usr/bin
/bin
/usr/sbin
/sbin

Common Tools

Here is a small list of common tools that I usually install with Homebrew to get you started — feel free to only install the ones you need:

# Core
brew install git
brew install coreutils
brew install pygments
# PHP
brew install php
brew install composer
# JavaScript
brew install node
brew install yarn

iTerm2

Okay — so this isn’t completely related to dotfiles, but I highly recommend replacing Apple’s default Terminal application if you haven’t already.

iTerm2 is my replacement of choice and is the one I have used for years. It is open source, extremely customizable, and comes with many useful features.

You can install it directly from the iTerm2 website, or by using Homebrew:

brew install iterm2

Tip: After installing, check out this GitHub repository of color schemes and choose one that works for you.

Zsh

Z shell (Zsh) is a Unix shell extension of Bourne shell — similar to Bash — and contains many new features and improvements:

• Auto-completion: Zsh tab completion is more feature rich than Bash and allows you to navigate options with ease.
• Auto-correction: Zsh is more forgiving when it comes to spelling and typos in commands by detecting errors and offering to correct them automatically.
• Themes: Zsh allows complete customization of your prompt including the ability to put text on the right side of the screen.
• … and many more!

Installation

Zsh is already installed on the latest editions of macOS. You should check that you have at least version 5.x (or greater) by running zsh --version. You can also choose to install the latest version using Homebrew:

brew install zsh

Note: Starting with macOS Catalina, Macs will now use Zsh as the default login shell and interactive shell across the operating system.

Oh My Zsh

Oh My Zsh is an open source, community-driven framework for configuration and management of Zsh on your system. It comes with many plugins and themes to choose from to customize your terminal experience.

Screenshot of my Oh My Zsh theme (built on the “avit” theme).

Installation

Install Oh My Zsh by running the installation command from the homepage:

sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

If it isn’t already, the installation procedure will ask you if you would like to make Zsh your default shell — if it doesn’t (or if you want to wait) — you can set Zsh as your default shell at any time by running the following command:

chsh -s $(which zsh)

Configuration

The default configuration that comes out of the box with Oh My Zsh is pretty good and is already a major improvement over the standard Bash shell. However, the power of Oh My Zsh is with the many customization options available. We will go over some of the basic choices — but if you want to deep dive into all of the customization options available, check out the Oh My Zsh Wiki.

The configuration file for Zsh is called .zshrc and lives in your home folder (~/.zshrc). Open it in your editor of choice and let’s customize:

Setting Your Zsh $PATH

The first line of the Oh My Zsh .zshrc should let you change the shell’s $PATH variable. Uncomment the export line and you are all set:

# If you come from bash you might have to change your $PATH.
export PATH=$HOME/bin:/usr/local/bin:$PATH

Theme

There are hundreds of themes to choose from, but the default Oh My Zsh theme is “robbyrussell”. The Oh My Zsh Wiki page on Themes displays a list of available themes along with screenshots.

You can change the theme by looking for the line that starts with ZSH_THEME and updating it:

# See https://github.com/ohmyzsh/ohmyzsh/wiki/Themes
ZSH_THEME="avit"

Plugins

Oh My Zsh comes bundled with hundreds of plugins that you can take advantage of. Again, check out the Oh My Zsh Wiki page on Plugins to get a better idea of the plugins available to you.

You can enable any plugin by adding its name to the plugins array found in your .zshrc file. Here are some good default ones to get your started:

# See https://github.com/ohmyzsh/ohmyzsh/wiki/Plugins-Overview
plugins=(git colorize brew osx)

… and here is what mine looks like:

plugins=(git brew colorize composer docker docker-compose gulp npm osx vagrant vscode nvm laravel)

Custom Scripts

Oh My Zsh lets you customize almost anything about your configuration — startup scripts, plugins, themes, etc. — all without having to fork and create your own version.

By default, your custom scripts will live in ~/.oh-my-zsh/custom but this can be changed to any directory you’d like by setting the $ZSH_CUSTOM variable in your .zshrc file.

You can read more information about overriding plugins/themes or creating your own plugins/themes by checking out the Oh My Zsh Wiki page on Customization. For now, let’s create a simple script that loads the zsh-syntax-highlighting package.

First, make sure zsh-syntax-highlighting is installed using Homebrew:

brew install zsh-syntax-highlighting

After installing some packages, Homebrew will sometimes output some extra information and installation instructions. You can review this information at any time by running brew info <formula>. For zsh-syntax-highlighting, it says something like this:

==> Caveats
To activate the syntax highlighting, add the following at the end of your .zshrc:
  source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

We could just add this line to our .zshrc as Homebrew suggests — but instead, let’s modularize our configuration by keeping this directive in its own custom script.

Create the file ~/.oh-my-zsh/custom/zsh-syntax-highlighting.zsh and copy in the suggested addition:

source /usr/local/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Note: Oh My Zsh will load all *.zsh files located in ~/.oh-my-zsh/custom last. You can name your custom scripts anything you would like.

You will need to reload your Terminal for the changes to take effect. After doing so, you can test that syntax highlighting is working by typing the following command:

echo "My current PATH: $PATH"

Screenshot showing the syntax highlighting package for Zsh.

Conclusion

We’ve only begun to scratch the surface of what is possible with configuration, customization, and potential time savers. In the next installment of this series — we will cover adding Homebrew Bundle, Mackup, and a few other goodies to this setup to help facilitate a fully functioning backup of all dotfiles and configuration. This backup can be deployed on any new machine to get yourself up and running with your preferred development environment as quickly as possible.

Continue to Dotfiles for Developers — Part 2…