Writing your first notebook

Shell Notebook is a free application for MacOS that lets you save, organize, and run your terminal commands. You can save your commands into files with a .ish file extension so you can come back to the commands you use most.

We’re going to be writing a Notebook to run source control commands for your website

No more forgetting commands and frantically searching through your bash history!

In this tutorial, we will be writing our first notebook to run our source control workflow on a repository.

Start by opening up Shell Notebook (if you don’t have it, you can download it here). When Shell Notebook opens up, you will see a single tab with a single cell. The text in the cell indicates my current working directory. For this new cell, that happens to be my home directory, /Users/ishaangandhi.

Writing commands

Click the cell and type the famous ls command. Now, either press the play button to the left of the cell, or press the shift and enter keys at the same time( ⇧+↩). When you run a command with Shell Notebook, the app automatically sources your zshell startup files (including your zshrc), and runs your code in zshell. Congratulations! 🎉 You’ve ran your first command.

Our goal is to set up a notebook to perform common git workflows in a repository. We’ll start by navigating to a repo on your computer. I’m going to navigate to my Github Pages repo, but the specific repo itself doesn’t matter.

Navigating Shell Notebook

If you’re familiar with the terminal, your first instinct might be to type a cd (change directory) command to navigate to where your repo is located. That will work, but the canonical Shell Notebook mode of navigation is to use native file navigation. Click the folder icon on the right side of your cell to open Finder. Navigate to your project, and when you find it, click the Open button.

You should notice the working directory change in your cell. Mine now looks like this:

Writing git commands

We’re now ready to write our git commands in our notebook. I use 4 commands very commonly when I work on my website, so I’m going to include those in my notebook. I’m going to replace the ls command in the first cell with

# Pull any new changes to my website
git pull origin master

Note, lines beginning with # are treated by zshell as a comment.

To create another cell, I can either press the gray circle with a plus right below the cell, or use the ⌘+N shortcut. I’m going to add a few more cells for the rest of my commands.

Note: The working directory of a new cell is the same as the working directory of the cell directly above it. Since our first cell is in the correct directory, all of our new cells will be as well.

I’ll add a cell for my add command:

# Stage changes to the markup
git add *.html

One for my commit command:

# Commit changes
git commit -m "added links"

And one for my push command:

# Push changes remotely
git push origin master

My notebook now looks like this:

Saving the notebook

I can run the cells once again, using the play button or the shift enter shortcut, and after confirming they work, we can save this notebook. Click File → Save, or Command-S to open the save dialog. I’m going to change the name of my notebook, and save it along with my repo.

Perfect! Whenever we need to perform synchronizations with this repo, we can now just double click the website.ish file in Finder, and our notebook will open up.

The notebook from this tutorial is available for download here. You will have to change the working directory of every cell to wherever your repository is located.

If you enjoyed this tutorial, please clap to show your appreciation 👏

Til next time!