My Dotfiles for macOS

🤩 Highlights

• Neovim editor configured with LunarVim IDE layer
• Starship prompt
• Shell support for both Zsh and Fish with 90% functional parity
• Flexible, terminal-based dev environment with Tmux
• Fast, idempotent setup with GNU Stow
• New Mac bootstrap based on thoughtbot’s Laptop
• Support for both Apple Silicon and Intel Macs

🗂️ Table of Contents

• Quick Setup
• Prerequisites
• New Mac Bootstrap
• Zsh or Fish?
  • Zsh Setup
  • Fish Setup
• Setting up iTerm2
• My Favorite Programming Fonts
• A Note about Vim performance and Ruby files
• Identifying Sources of Slow Startup Times (Zsh)
• Some of my favorite dotfile repos
• Helpful web resources on dotfiles, et al.
• License

⚡️ Quick Setup

Make sure macOS is up to date and you have installed the required software.

Clone this repo.

git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles

Read the setup script.

less ~/dotfiles/setup.sh

Run the setup script.

bash ~/dotfiles/setup.sh

✅ Prerequisites

The dotfiles assume you are running macOS with (at minimum) the following software pre-installed:

• Git
• Homebrew (including coreutils)
• asdf
• Ruby
• Node.js
• Zsh and/or Fish
• Neovim
• Tmux
• Starship

All of the above and more are installed with my fork of Laptop.

🌟 New Mac Bootstrap

This is what I would do if I bought a new Mac computer today. The steps below assume you have already completed the basics:

• Log in to iCloud
• Check for software updates
• Install Xcode Command Line Tools

💻 1. Run my fork of thoughtbot’s Laptop

▹ github.com/joshukraine/laptop

Download the mac script:

curl --remote-name https://raw.githubusercontent.com/joshukraine/laptop/main/mac

Download .local.laptop for additional customizations:

curl --remote-name https://raw.githubusercontent.com/joshukraine/dotfiles/master/laptop/.laptop.local

Review both scripts before proceeding:

less mac

less .laptop.local

Execute the mac script:

sh mac 2>&1 | tee ~/laptop.log

I’ve made the following changes to my fork of Laptop:

• Install asdf via git instead of Homebrew
• Comment out Heroku-related code
• Comment out unused Homebrew taps and formulae

It is worth noting that the Laptop script (mac) is idempotent and can be safely run multiple times to ensure a consistent baseline configuration.

⚠️ 2. Check for Stow conflicts

The dotfiles setup.sh script uses GNU Stow to symlink all the config files to your $HOME directory. If you already have an identically-named file/directory in $HOME (e.g. ~/.zshrc leftover from installing Laptop), this will cause a conflict, and Stow will (rightly) abort with an error.

The setup script will try to detect and backup these files ahead of Stow, but it’s still a good idea to check your $HOME directory as well as $HOME/.config and $HOME/.local/bin.

📍 3. Clone and setup the dotfiles

Clone

git clone https://github.com/joshukraine/dotfiles.git ~/dotfiles

Read

less ~/dotfiles/setup.sh

Setup

bash ~/dotfiles/setup.sh

If you do encounter Stow conflicts, resolve these and run setup again. The script is idempotent, so you can run it multiple times safely.

🌙 4. Install LunarVim

LunarVim describes itself as “An IDE layer for Neovim with sane defaults.” I’ve used it for some time now and found it to be delightful. It’s pretty stable and has made configuring Neovim much simpler.

▹ lunarvim.org/docs/installation

⚡️ 5. Install Zap

Zap describes itself as a “minimal zsh plugin manager that does what you expect.”

▹ zapzsh.org

After copying/pasting the install command for Zap, be sure to add the --keep flag to prevent Zap from replacing you existing .zshrc file.

🍺 6. Install remaining Homebrew packages

Review the included Brewfile and make desired adjustments.

less ~/Brewfile

Install the bundle.

brew bundle install

🛠️ 7. Complete post-install tasks

• [ ] Set up iTerm2 preferences. (Now handled automatically in setup.sh script)
• [ ] Install Tmux plugins with <prefix> + I (tmux-plugins/tpm)
• [ ] Launch LunarVim (lvim) and run :checkhealth. Resolve errors and warnings.
• [ ] Set up 1Password CLI for managing secrets.
• [ ] Set up 1Password SSH key management.
• [ ] Add personal data as needed to *.local files such as ~/.gitconfig.local, ~/.laptop.local, ~/dotfiles/local/config.fish.local.
• [ ] If using Fish, customize your setup by running the fish_config command.

Zsh or Fish?

Having used both Zsh and Fish for several years, I’ve decided to keep my configs for both. One thing I particularly love about Fish is the concept of abbreviations over aliases. Happily, there is now zsh-abbr which brings this functionality to Zsh.

▹ Fish abbr docs

My Zsh and Fish configs mostly have functional parity:

• Same prompt (Starship)
• Same essential abbreviations and functions

Zsh Setup

Zsh is now the default shell on macOS. However, it’s helpful to add an entry enabling the Homebrew version of Zsh ($HOMEBREW_PREFIX/bin/zsh) instead of the default (/bin/zsh) version.

Ensure that you have Zsh from Homebrew. (which zsh) If not:

brew install zsh

Add Zsh (Homebrew version) to /etc/shells:

echo $HOMEBREW_PREFIX/bin/zsh | sudo tee -a /etc/shells

Set it as your default shell:

chsh -s $(which zsh)

Install Zap. (Required for functional parity with Fish) Restart your terminal.

Fish Setup

Install Fish from Homebrew:

 brew install fish

Add Fish to /etc/shells:

echo $HOMEBREW_PREFIX/bin/fish | sudo tee -a /etc/shells

Set it as your default shell:

chsh -s $(which fish)

Restart your terminal. This will create the ~/.config and ~/.local directories if they don’t already exist.

Setting up iTerm2

UPDATE: This is now done automatically if you run setup.sh.

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 > Settings. (⌘,)
3. Under the General tab, select “Preferences”.
4. Check the box labeled “Load preferences from a custom folder or URL:”
5. Press “Browse” and navigate to ~/dotfiles/iterm/com.googlecode.iterm2.plist.
6. Press “Open”.
7. Restart iTerm2.

My Favorite Programming Fonts

Over the years, I’ve branched out to explore a variety of mono-spaced fonts, 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
• Comic Code

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 install --cask font-fira-code

# Patched variant
$ brew install --cask font-fira-code-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

Identifying Sources of Slow Startup Times (Zsh)

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 (Integralist/ProVim)
• Trevor Brown (Stratus3D/dotfiles)
• Chris Toomey (christoomey/dotfiles)
• thoughtbot (thoughtbot/dotfiles)
• Lars Kappert (webpro/dotfiles)
• Ryan Bates (ryanb/dotfiles)
• Ben Orenstein (r00k/dotfiles)
• Joshua Clayton (joshuaclayton/dotfiles)
• Drew Neil (nelstrom/dotfiles)
• Kevin Suttle (kevinSuttle/OSXDefaults)
• Carlos Becker (caarlos0/dotfiles)
• Zach Holman (https://github.com/holman/dotfiles/)
• Mathias Bynens (https://github.com/mathiasbynens/dotfiles/)
• Paul Irish (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
• 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–2023 Joshua Steele. MIT License