Alyssa’s Guide to a Good Terminal

Your terminal is your home. Just like your real home, we want this thing to be nice. We’re there all dang day!

Even small improvements in your terminal can have huge impacts on your productivity. We don’t get paid to sit in front of a computer, we get paid to deliver business value. The faster you do your work, the less time you have to sit in front of your computer.

I’m going to teach you how I like my terminal set up. These are hard-earned opinions. I advise you to start with my opinions until you have enough experience to develop your own.

This document was last updated on 13 SEPTEMBER 2023

First, a note on documentation conventions

When you’re reading example commands, it can be hard to understand what part of a command (if any) you should replace. Here are two common conventions to be aware of:

• If you see angle brackets ‹like this› that is always a sign that you need to replace the stuff inside the angle brackets with something specific to you. Don’t leave the angle brackets behind! For example, if you saw a link like this:
• https://this.is.an.example.url/users/‹your alias›
• The author of that documentation expects you to replace ‹your alias› with your actual alias, without the angle brackets
• Finished example: https://this.is.an.example.url/alyssahursh
• If you see example commands that start with a leading dollar sign, that is the author telling you “run this command in your terminal” — they don’t mean for you to include the dollar sign when you copy the command. For example, if you saw this instruction:
• Run $ cd ~/.ssh
• Only copy cd ~/.ssh — don’t copy the $.

iTerm2

I prefer iTerm2 over Apple’s default terminal. Why? One time my brother made fun of me for using the default terminal. That’s it. I have been using iTerm2 for so long that I don’t how it differs from terminal. The rest of these instructions all assume you’re using iTerm2. They probably work in terminal too, but I haven’t tested that myself.

You can install iTerm2 from the iTerm2 website.

One deficiency of iTerm2 is that it doesn’t default to unlimited scrollback. Scrollback is how far in your terminal output you can scroll back before the output gets cut off. iTerm2’s default is (I think) 1,000 lines, which often isn’t enough.

To set iTerm2’s scrollback buffer to “unlimited”:

1. Make sure that iTerm2 is open and “in focus” (i.e. it’s the active application)
2. command + comma (⌘,) to open iTerm2’s preferences — please practice using this key command, this is the default key command to open application preferences for the application in focus. I need you to practice using keyboard shortcuts all the time; it is critical that you become fluent with your keyboard.
3. Click “Profiles”
4. Click “Terminal”
5. Under “Scrollback Buffer” check “Unlimited scrollback”
6. command + Q (⌘Q) to close iTerm2 entirely — please practice using this key command to close the current application rather than clicking the little red circle
7. command + space bar (⌘ + space) to open Spotlight Search
8. Search for iTerm and hit enter to open iTerm again — please practice always using Spotlight Search to open applications

zsh

zsh or “Z shell” (pronounced “zosh” not “zish”) is the default shell that your (post-2019) MacBook Pro shipped with from the manufacturer.

A shell is a small piece of software that passes commands from the end-user (that’s you!) through the terminal to the kernel (that’s the deep insides of your computer). If you didn’t have a shell, your terminal wouldn’t know how to send your commands to the kernel.

The name “zsh” is an in-joke. It was the alias of a teaching assistant named Zhong Shao at Princeton in 1990, when the program was originally created. Now you know.

You can tell what shell your terminal is using by running the command echo $SHELL

echo is a built-in Linux tool that prints strings to the screen. SHELL is an environment variable on your computer. echo $SHELL will print the value of the variable SHELL to your screen. Confirm for yourself that your shell is zsh.

oh-my-zsh

oh-my-zsh is a framework for managing your zsh configuration. This sounds boring, but I assure you it is not.

To install oh-my-zsh, find the curl command in the installation guide. It probably looks like this:

(remember that the $ means “in your terminal” — don’t copy and paste that dollar sign!)

Before you run this installation command, it’s important to understand what will happen:

1. The tool will install a directory at ~/.oh-my-zsh
2. The tool will replace your existing ~/.zshrc file

Your ~/.zshrc file is the file that runs when your shell starts. It’s a place for you to configure your shell, add to your PATH, and create aliases, among other things.

(As an aside, rc in ~/.zshrc is a tribute to much older software; it stands for “runcom” or “runcon” short for “run command” or “run control” — a reference to MIT CTSS, the precursor to UNIX, developed in 1965. Now you know.)

Replacing your ~/.zshrc file is a big deal, particularly if you have made changes to your file and would like to preserve those changes. Because this is a big deal, oh-my-zsh will actually save a copy of your old ~/.zshrc file at ~/.zshrc.pre-oh-my-zsh. If you need to get your old file back, that’s where it is.

Now that we know what will happen, go ahead and run the installation command.

In order for the installation to take effect in your current shell, you might need to execute the contents of your ~/.zshrc file. To do so (without restarting your terminal) run source ~/.zshrc

People like oh-my-zsh because it has “themes” that can make your terminal pretty. Please do not spend a bunch of time configuring your oh-my-zsh theme, changing colors, etc (until you have a full time job offer, then do whatever you want). The goal here is not to make your terminal pretty, it’s to make it practical. I use the default “robbyrussell” theme, which shows me:

• What directory I’m in
• What branch I’m on
• Whether my git working tree is clean (a small x symbol at the end of the line)

Many people also like to have the command line print the current timestamp so that they can see exactly when they ran a particular command. Some themes include the timestamp.

To change the theme, you’ll need to open your new ~/.zshrc file in vim. If you aren’t already familiar with vim, please take a moment with my vim crash course. Yes, we could technically open this file in a different text editor, but we’re software engineers and we’re already in our terminal, and we can quickly do this work in vim — the more that you force yourself to use vim, the more comfortable you’ll be using it.

vim ~/.zshrc to open the file with vim.

You’ll see that you now have a really long ~/.zshrc file! It has tons of options that are commented out. You can read through those options and test out the features that sound interesting to you by uncommenting the lines that you want to have take effect.

zsh-autosuggestions

zsh-autosuggestions is one of three command line tools I cannot live without. It offers command completion suggestions while you’re typing so that you only have to write the first piece of a command. Once you’ve written enough of the command that you can see the rest of the command you want as a suggestion, you can use the right arrow on your keyboard to complete your command.

Follow the zsh-autosuggestions install instructions for installing this tool with oh-my-zsh (summarized below).

Run this git clone command to clone the zsh-autosuggestions repo:

Open your ~/.zshrc file with vim ~/.zshrc and add zsh-autosuggestions to the pluggins section.

Execute the contents of your ~/.zshrc file with source ~/.zshrc

fzf

fuzzy finder! fzf turbo charges “reverse-i-search”

Before you install fzf, let’s talk about what “reverse-i-search” is. I know you know how to “up arrow” your way to old commands. Did you know that you can search them instead? Type ctrl + r into your terminal. This will open “reverse-i-search” (you can tell, because your command line will now say “reverse-i-search” or "back-i-search"). In this mode, you can start typing commands you’ve typed in the past, and you’ll see matches with past commands as you type. With a little practice and some tutorials, reverse-i-search can be a very powerful tool. reverse-i-search is honestly great just on its own, but fzf adds a little extra sugar.

While you’re searching, fzf will show you many potential matching commands. It also lets you search for matching text in the middle of previous commands, and it’s pretty good at guessing correctly even when you have typos. Now when you think “I’m pretty sure I’ve run this command before” you can run ctrl + r, start typing whatever you can remember, and see a bunch of potential command matches.

To install fzf, follow the instructions from the (copied below):

Restart your shell with source ~/.zshrc

To test it out, run ctrl + r and start typing a previous command.

If you’re in fzf search mode and you don’t want to be, ctrl + c to quit the command and regain control of your command line (this is always true of ctrl + c — want a fresh command line? ctrl + c will reset it for you).

z (jump around)

z is a tool that creates a database of the directories that you cd into, based on frequency and recency. Instead of running cd ../../../ back and forth into various directories you can run z ‹part of a directory name› and z will guess what directory you mean. It’s good. Doesn’t matter where I am on my machine, z takes me exactly where I want to be.

The installation instructions for z are a little thin. This should work unless something has changed:

Once installed, cd around a bunch into directories that you want in your database, then run z ‹some directory‹ — as long as that directory name is reasonably unique, z should take you straight to that directory. Learning what directory shorthand works takes a little getting used to, but you’ll get there with practice. Learning z will save you so much time and more importantly, so much mental effort! Our brains only have so many energy to do complex things each day. Don’t waste your precious brain power manually cd’ing between directories.

That’s it!

I’ve been asking friends for their terminal tooling advice for several years. These are the only tools that have survived the transfer to new machines as I’ve replaced old laptops and development hosts. I like to keep my custom tool list relatively short and simple, because the more custom tooling you add the more likely it is that something will break and cause you a headache down the road. These tools have served me well for many years.