Software Engineering, Web Development and 3D Graphics

Sync iTerm2 Profile With Dotfiles Repository

You have planned ahead. Everything you need to get setup on the new MacBook Pro is stored in your dotfile repository hosted on GitHub. You fire up iTerm2, clone down the repository, run the setup script and restart iTerm. But something’s not right. Bash and Zsh are configured correctly, but they don’t look right. All the colors are off. Vim looks horrific. Looks like you forgot to transfer your iTerm2 profile to your new laptop. Everything from colors to scrollback options are stored in your iTerm2 configuration, which is hidden away somewhere on your file system on your old laptop. Transferring all your iTerm2 settings manually is a pain. Thankfully there is a better way. In this post I show you how to store your iTerm2 profile in your dotfiles repository along with everything else.

First get iTerm2 configured the way you like it (in the scenario above, this would mean using your old laptop). Once you have iTerm2 configured the way you like navigate to the preferences window (iTerm2 -> preferences). and click on the General tab. Towards the bottom of the window you should see an option that says “Load preferences from a custom folder or URL”. Check this option.

folder option

Once this option is checked an input box with a browse button next to it should be enabled below the checkbox you just checked. This allow us to load and save iTerm2 config files to the specified directory. Before you continue you will want to created a directory to hold the config file. Using the shell or Finder navigate to your dotfile repository and create a directory to store the iTerm2 config file. I named mine iterm2_profile. After creating the directory go back to the iTerm2 settings and click the browse button next to the input box for the iterm2 config file path/URL and select the directory you just created.

choose iTerm2 directory

Once the directory has been selected click the “Save Settings to Folder” button. An XML config file should be created in the folder you specified.

settings complete

Navigate to the directory you specified and you should see the config file. Assuming you are using Git to manage your dotfiles, you should also be able to hop into the shell and run git status. Git should show the new directory in the status message. Run git add . to add the config file to the Git stage. Commit the file and push it up to your hosted dotfile repository. Now that the file is checked in to your Git repository every time you make a change to your iTerm2 configuration via the GUI it will appear as a change to the config file in your dotfile repo, which you can then commit or discard.

Now getting iTerm2 setup on a new laptop is as simple as check the “Load preferences from folder” option and navigating to the file that already exists inside your dotfile repository.

Hopefully this post has been useful to you. If you have any questions feel free to contact me.

Update 2/8/2017

You actually don’t have to use the iTerm2 GUI to load the preferences. It’s possible load them from the command line. This makes it easy to load them from a setup script in your dotfile repository. All you need are these two commands:

# Specify the preferences directory
defaults write com.googlecode.iterm2.plist PrefsCustomFolder -string "~/dotfiles/iterm2"
# Tell iTerm2 to use the custom preferences in the directory
defaults write com.googlecode.iterm2.plist LoadPrefsFromCustomFolder -bool true

Thanks to Lasse Magnussen for these commands!