My Dotfiles for macOS

dotfiles screenshot

These are the dotfiles I use on my Mac computers, currently running macOS Catalina (10.15). They are geared primarily towards web development with Rails, React, and Vue. I use a terminal-based development environment built on Fish, Tmux, and Neovim. Also included are my iTerm2 and Alacritty profiles.

Table of Contents

Mac Bootstrap Script

Need to provision a new Mac from scratch? My Mac Bootstrap script installs and configures the software, dotfiles, and general preferences I use for web development.

Provision a new Mac with Mac Bootstrap.

NOTE: Mac Bootstrap automatically clones and installs this dotfiles repo.


The dotfiles assume you are running macOS with the following software pre-installed:

All of the above and more are included in Mac Bootstrap


The install script will create the needed directories and symlinks for your setup, adding config files for both Zsh and Fish.

  1. Setup your shell. (See Fish/Zsh instructions below.)

  2. Run the installation script.

$ git clone ~/dotfiles
$ bash ~/dotfiles/

Fish or Zsh?

I have used Zsh for years and really liked it. Recently I've switched to Fish, and am loving that too! I've kept both of my configs intact in my dotfiles. Running the install script will link configs for both Fish and Zsh shells.

Zsh Setup

  1. Install zsh: $ brew install zsh
  2. Set it as your default shell: $ chsh -s $(which zsh)
  3. Install Oh My Zsh.
  4. Restart your computer.

Fish Setup

  1. Install Fish: $ brew install fish
  2. Add Fish to /etc/shells: $ echo /usr/local/bin/fish | sudo tee -a /etc/shells
  3. Set it as your default shell: $ chsh -s /usr/local/bin/fish
  4. Restart your terminal emulator. This will create the ~/.config and ~/.local directories if they don’t already exist.

Post-install Tasks

After running there are still a couple of things that need to be done.

  • Add machine-specific configs as needed. (see Machine-specific Configs below)
  • Set up iTerm2 or Alacritty profile (see details below).
  • Complete Brew Bundle with brew bundle install
  • Add personal data to ~/.gitconfig.local, ~/.vimrc.local, ~/dotfiles/local/, and ~/.zshrc.local as needed.
  • After opening Neovim, run :checkhealth and resolve errors/warnings.
  • If using Fish, customize your setup by running the fish_config command.

Setting up iTerm2

Thanks to a great blog post by Trevor Brown, I learned that you can quickly set up iTerm2 by exporting your profile. Here are the steps.

  1. Open iTerm2.
  2. Select iTerm2 > Preferences.
  3. Under the General tab, check the box labeled "Load preferences from a custom folder or URL:"
  4. Press "Browse" and point it to ~/dotfiles/machines/<hostname>/com.googlecode.iterm2.plist.
  5. Restart iTerm2.

Setting up Alacritty

Getting set up after a fresh install is simple.

  1. Tweak preferences in ~/dotfiles/machines/<hostname>/alacritty.yml.
  2. Uncomment Alacritty terminfo lines in ~/dotfiles/machines/<hostname>/tmux.conf.custom
  3. Run Alacritty!

Machine-specific Configs

I regularly use two Mac computers: a desktop and laptop. Most of my configs are identical between the two, but there are some some differences. I also occasionally install my dotfiles on other machines (family computer, wife's computer, your computer if I can get to it... 😈)

For this reason, I've introduced a machines/ folder where I keep configs that are specific to a given computer. Machine-specific configs should be stored in sub-folders of machines/ and named for the hostname of that machine. The overall structure looks like this:

β”œβ”€β”€ joshuas-imac
β”‚Β Β  β”œβ”€β”€ Brewfile -> ../../Brewfile
β”‚Β Β  β”œβ”€β”€ Brewfile.lock.json
β”‚Β Β  β”œβ”€β”€ alacritty.yml
β”‚Β Β  β”œβ”€β”€
β”‚Β Β  β”œβ”€β”€ colorscheme.vim
β”‚Β Β  β”œβ”€β”€ com.googlecode.iterm2.plist
β”‚Β Β  β”œβ”€β”€ starship.toml
β”‚Β Β  └── tmux.conf.custom
└── joshuas-mbp15
    β”œβ”€β”€ Brewfile -> ../../Brewfile
    β”œβ”€β”€ Brewfile.lock.json
    β”œβ”€β”€ alacritty.yml
    β”œβ”€β”€ colorscheme.vim
    β”œβ”€β”€ com.googlecode.iterm2.plist
    β”œβ”€β”€ starship.toml
    └── tmux.conf.custom

My current Homebrew Bundle approach depends heavily on the above setup. I have a Fish function (bb) which runs a machine-specific Brewfile based on the hostname of the current computer. (See fish/functions/


My all-time favorite colorscheme for code-editing is Solarized Dark. That said, there are times when I like to dabble with something new, just to have some variety. In the past it's been painful to switch colorschemes for vim since I also needed to find a suitable profile for iTerm2, make tweaks to tmux.conf, etc. Sometimes the colorschemes were 24-bit only (think set termguicolors) and others were more simple (256-color), like the original version of Solarized.

I've now introduced an approach for switching between colorschemes which I hope will be more straightforward. It's still not a one-step operation, but all the colorschemes and their individual settings can be stored simultaneously, and switching between them takes minimal effort.

One Half Dark Screenshot

Example of a React app with the One Half Dark colorscheme

At the time of this writing, I've incorporated 11 colorschemes, all of which require true color support.

  1. Gruvbox
  2. Material
  3. Night Owl
  4. Nightfly
  5. Nord Vim
  6. Oceanic Next
  7. One Half Dark
  8. Solarized Dark
  9. Tender
  10. Vim One
  11. vim-monokai-tasty

Here's how everything is organized:

1. Colorschemes

The settings for individual colorschemes are stored in separate files. To add a new colorscheme, add a file for it here.

└── colorschemes
    β”œβ”€β”€ gruvbox.vim
    β”œβ”€β”€ material.vim
    β”œβ”€β”€ night-owl.vim
    β”œβ”€β”€ nightfly.vim
    β”œβ”€β”€ nord.vim
    β”œβ”€β”€ oceanic-next.vim
    β”œβ”€β”€ onehalfdark.vim
    β”œβ”€β”€ solarized.vim
    β”œβ”€β”€ tender.vim
    β”œβ”€β”€ vim-monokai-tasty.vim
    └── vim-one.vim

2. Machine-specific Config

Every machine I manage has a colorscheme.vim file in its directory. That file defines in one line which colorscheme should be used. For example:

" machines/joshuas-imac/colorscheme.vim

exe 'source' stdpath('config') . '/colorschemes/gruvbox.vim'

This theme is then loaded in nvim/init.vim with the following line (see the Appearance section):

" nvim/init.vim

exe 'source' "$DOTFILES/machines/$HOST_NAME/colorscheme.vim"

3. Terminal Colorschemes

Since I use vim in the terminal, I need corresponding iTerm2 or Alacritty colorschemes for every vim colorscheme. My iTerm2 colorschemes are stored in itermcolors/, but of course must be added manually to the iTerm profile. Alacritty colorschemes are defined in ~/dotfiles/machines/<hostname>/alacritty.yml.

Multiple pre-made colorschemes are available online for both iTerm2 and Alacritty:

4. Tmux Custom Overrides

The last tweak is for Tmux. I like to set custom hex color codes for the status bar depending on which colorscheme I'm using. Each machine profile now has its own tmux.conf.custom file. In particular, it can be nice to adjust the background of the status bar to better match the current colorscheme.

The main tmux.conf file contains all the settings that Tmux needs. However, any setting that is re-declared in machines/$HOST_NAME/tmux.conf.custom will override the defaults.

# machines/joshuas-imac/tmux.conf.custom

# Gruvbox {{{
setw -g window-status-style fg=$BLACK,bg=$BRIGHT_BLUE
setw -g window-status-current-style fg="#fbf1c7",bg=$BRIGHT_RED
set -g pane-border-style bg=default,fg="#665c54"
set -g status-left "#[fg=$BRIGHT_GREEN][#S] #[fg=$RED]w#I #[fg=$BLUE]p#P"
set -g status-style bg="#3c3836"
# }}}

# Material {{{
# set -g status-style bg="#2c3b41"
# }}}


My Favorite Programming Fonts

I've recently branched out to explore some of the different mono-spaced fonts available, both free and premium. Here is a list of my favorites.

Free Fonts

Included in my Brewfile and installed by default via Homebrew Cask Fonts

Premium Fonts

You have to give people money if you want these. πŸ€‘


I first discovered ligatures through Fira Code, which IMO is probably the king of programming fonts. After using Fira Code, it's hard to go back to a sans-ligature typeface. Therefore †all the fonts I've included in my fave's list do include ligatures, although some have more than others.

† Operator Mono does not include ligatures but can be easily patched to add them.

Nerd Font Variants

I use Devicons in my editor, and these require patched fonts in order to display properly. For most free fonts, there are pre-patched Nerd Font variants that include the various glyphs and icons.

Homebrew Cask Fonts includes both original and Nerd Font variants. For example:

# Original font
$ brew cask install font-fira-code

# Patched variant
$ brew cask install font-firacode-nerd-font

If using a font that does not have a patched variant (e.g. MonoLisa) iTerm2 has an option to use an alternate font for non-ASCII characters.


A Note about Vim performance and Ruby files

I recently discovered a resolution to some significant performance issues I had been experiencing running Vim on macOS. These issues were particularly painful when editing Ruby files. I've documented what I learned here:

What I've learned about slow performance in Vim

Vim vs. Neovim

UPDATE: After "trying" Neovim for nearly two years, I'm ready to make the switch permanent. Instead of linking to my .vimrc as described below, I've now moved all my configs over to ~/.config/nvim/init.vim.

I'm currently trying out Neovim, and so far things are working nicely. For now I have things set up so I can run either Vim or Neovim interchangeably. This is accomplished by telling Neovim's config file (~/.config/nvim/init.vim) to source the standard Vim config file (~/.vimrc).

More info:

Identifying Sources of Slow Startup Times

The .zshrc script can be profiled by touching the file ~/.zshrc.profiler and starting a new login shell. To see the top 20 lines that are taking the most time use the zshrc_profiler_view. zshrc_profiler parameters are number of lines to show (20) and path to profiler log file ($TMPDIR/zshrc_profiler.${PID}log).

Some of my favorite dotfile repos

Helpful web resources on dotfiles, et al.


Copyright © 2014–2020 Joshua Steele. MIT License


:round_pushpin: My dotfiles for macOS using Fish/Zsh, Neovim, and Tmux

Dotfiles Info

⭐ Stars 196
πŸ”— Homepage
πŸ”— Source Code
πŸ•’ Last Update 8 months ago
πŸ•’ Created 8 years ago
🐞 Open Issues 1
βž— Star-Issue Ratio 196
😎 Author joshukraine