My Dotfiles for macOS

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
• Prerequisites
• Installation
• Fish or Zsh?
  • Zsh Setup
  • Fish Setup
• Post-install Tasks
• Setting up iTerm2
• Setting up Alacritty
• Machine-specific Configs
• Colorschemes
  • 1. Colorschemes
  • 2. Machine-specific Config
  • 3. Terminal Colorschemes
  • 4. Tmux Custom Overrides
  • Useful Colorscheme Links
• My Favorite Programming Fonts
  • Free Fonts
  • Premium Fonts
  • Ligatures
  • Nerd Font Variants
  • Useful Font Links
• A Note about Vim performance and Ruby files
• Vim vs. Neovim
• Identifying Sources of Slow Startup Times
• Some of my favorite dotfile repos
• Helpful web resources on dotfiles, et al.
• License

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.

Prerequisites

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

• Git
• Homebrew (including coreutils)
• Ruby
• Node.js
• Fish or Zsh
• Oh-My-Zsh (if using zsh)
• Neovim
• Tmux
• asdf
• Starship

All of the above and more are included in Mac Bootstrap

Installation

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 https://github.com/joshukraine/dotfiles.git ~/dotfiles
$ bash ~/dotfiles/install.sh

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 install.sh 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/config.fish.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:

machines/
├── joshuas-imac
│   ├── Brewfile -> ../../Brewfile
│   ├── Brewfile.lock.json
│   ├── alacritty.yml
│   ├── colors.fish
│   ├── colorscheme.vim
│   ├── com.googlecode.iterm2.plist
│   ├── starship.toml
│   └── tmux.conf.custom
└── joshuas-mbp15
    ├── Brewfile -> ../../Brewfile
    ├── Brewfile.lock.json
    ├── alacritty.yml
    ├── colors.fish
    ├── 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/bb.fish)

Colorschemes

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.

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.

nvim/
└── 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:

• iTerm2 colorschemes
• Alacritty colorschemes

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"
# }}}

[...]

Useful Colorscheme Links

• http://vimcolors.com/
• https://www.slant.co/topics/480/~best-vim-color-schemes

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

• Fira Code
• Cascadia Code
• Victor Mono
• JetBrains Mono
• Iosveka

Premium Fonts

You have to give people money if you want these. 🤑

• Operator Mono
• MonoLisa
• Dank Mono

Ligatures

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.

Useful Font Links

• Nerd Font Downloads
• Programming Fonts - Test Drive
• Homebrew Cask Fonts

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:

• https://neovim.io/doc/user/nvim.html#nvim-from-vim
• https://neovim.io/doc/user/vim_diff.html#vim-differences

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

• Pro Vim (https://github.com/Integralist/ProVim)
• Trevor Brown (https://github.com/Stratus3D/dotfiles)
• Chris Toomey (https://github.com/christoomey/dotfiles)
• thoughtbot (https://github.com/thoughtbot/dotfiles)
• Lars Kappert (https://github.com/webpro/dotfiles)
• Ryan Bates (https://github.com/ryanb/dotfiles)
• Ben Orenstein (https://github.com/r00k/dotfiles)
• Joshua Clayton (https://github.com/joshuaclayton/dotfiles)
• Drew Neil (https://github.com/nelstrom/dotfiles)
• Kevin Suttle (https://github.com/kevinSuttle/OSXDefaults)
• Carlos Becker (https://github.com/caarlos0/dotfiles)
• Zach Holman (https://github.com/holman/dotfiles/)
• Mathias Bynens (https://github.com/mathiasbynens/dotfiles/)
• Paul Irish (https://github.com/paulirish/dotfiles)

Helpful web resources on dotfiles, et al.

• http://dotfiles.github.io/
• https://medium.com/@webprolific/getting-started-with-dotfiles-43c3602fd789
• http://code.tutsplus.com/tutorials/setting-up-a-mac-dev-machine-from-zero-to-hero-with-dotfiles--net-35449
• https://github.com/webpro/awesome-dotfiles
• http://blog.smalleycreative.com/tutorials/using-git-and-github-to-manage-your-dotfiles/
• http://carlosbecker.com/posts/first-steps-with-mac-os-x-as-a-developer/
• https://mattstauffer.co/blog/setting-up-a-new-os-x-development-machine-part-1-core-files-and-custom-shell

License

Copyright © 2014–2020 Joshua Steele. MIT License