Dealing with Emergencies in Git

The stockings were hung by the chimney with care,
In hopes that version control soon would be there.

This summer I moved to the UK with my partner, and the onslaught of the Christmas holiday season began around the end of October (October!). It does mean that I’ve had more than a fair amount of time to come up with horrible Git analogies for this article. Analogies, metaphors, and comparisons help the learner hook into existing mental models about how a system works. They only help, however, if the learner has enough familiarity with the topic at hand to make the connection between the old and new information.

Let’s start by painting an updated version of Clement Clarke Moore’s Christmas living room. Empty stockings are hung up next to the fireplace, waiting for Saint Nicholas to come down the chimney and fill them with small treats. Holiday treats are scattered about. A bowl of mixed nuts, the holiday nutcracker, and a few clementines. A string of coloured lights winds its way up an evergreen.

Perhaps a few of these images are familiar, or maybe they’re just settings you’ve seen in a movie. It doesn’t really matter what the living room looks like though. The important thing is to ground yourself in your own experiences before tackling a new subject. Instead of trying to brute-force your way into new information, as an adult learner constantly ask yourself: ‘What is this like? What does this remind me of? What do I already know that I can use to map out this new territory?’ It’s okay if the map isn’t perfect. As you refine your understanding of a new topic, you’ll outgrow the initial metaphors, analogies, and comparisons.

With apologies to Mr. Moore, let’s give it a try.

Getting Interrupted in Git

When on the roof there arose such a clatter!

You’re happily working on your software project when all of a sudden there are freaking reindeer on the roof! Whatever you’ve been working on is going to need to wait while you investigate the commotion.

If you’ve got even a little bit of experience working with Git, you know that you cannot simply change what you’re working on in times of emergency. If you’ve been doing work, you have a dirty working directory and you cannot change branches, or push your work to a remote repository while in this state.

Up to this point, you’ve probably dealt with emergencies by making a somewhat useless commit with a message something to the effect of ‘switching branches for a sec’. This isn’t exactly helpful to future you, as commits should really contain whole ideas of completed work. If you get interrupted, especially if there are reindeer on the roof, the chances are very high that you weren’t finished with what you were working on.

You don’t need to make useless commits though. Instead, you can use the stash command. This command allows you to temporarily set aside all of your changes so that you can come back to them later. In this sense, stash is like setting your book down on the side table (or pushing the cat off your lap) so you can go investigate the noise on the roof. You aren’t putting your book away though, you’re just putting it down for a moment so you can come back and find it exactly the way it was when you put it down.

Let’s say you’ve been working in the branch waiting-for-st-nicholas, and now you need to temporarily set aside your changes to see what the noise was on the roof:

$ git stash

After running this command, all uncommitted work will be temporarily removed from your working directory, and you will be returned to whatever state you were in the last time you committed your work.

With the book safely on the side table, and the cat safely off your lap, you are now free to investigate the noise on the roof. It turns out it’s not reindeer after all, but just your boss who thought they’d help out by writing some code on the project you’ve been working on. Bless. Rolling your eyes, you agree to take a look and see what kind of mischief your boss has gotten themselves into this time.

You fetch an updated list of branches from the remote repository, locate the branch your boss had been working on, and checkout a local copy:

$ git fetch
$ git branch -r
$ git checkout -b helpful-boss-branch origin/helpful-boss-branch

You are now in a local copy of the branch where you are free to look around, and figure out exactly what’s going on.

You sigh audibly and say, ‘Okay. Tell me what was happening when you first realised you’d gotten into a mess’ as you look through the log messages for the branch.

$ git log --oneline
$ git log

By using the log command you will be able to review the history of the branch and find out the moment right before your boss ended up stuck on your roof.

You may also want to compare the work your boss has done to the main branch for your project. For this article, we’ll assume the main branch is named master.

$ git diff master

Looking through the commits, you may be able to see that things started out okay but then took a turn for the worse.

Checking out a single commit

Using commands you’re already familiar with, you can rewind through history and take a look at the state of the code at any moment in time by checking out a single commit, just like you would a branch.

Using the log command, locate the unique identifier (commit hash) of the commit you want to investigate. For example, let’s say the unique identifier you want to checkout is 25f6d7f.

$ git checkout 25f6d7f

Note: checking out '25f6d7f'.

You are in 'detached HEAD' state. You can look around,
make experimental changes and commit them, and you can
discard any commits you make in this state without
impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may do so (now or later) by using @-b@ with the checkout command again. Example:

$ git checkout -b new_branch_name

HEAD is now at 25f6d7f... Removed first paragraph.

This is usually where people start to panic. Your boss screwed something up, and now your HEAD is detached. Under normal circumstances, these words would be a very good reason to panic.

Take a deep breath. Nothing bad is going to happen. Being in a detached HEAD state just means you’ve temporarily disconnected from a known chain of events. In other words, you’re currently looking at the middle of a story (or branch) about what happened – and you’re not at the endpoint for this particular story.

Git allows you to view the history of your repository as a timeline (technically it’s a directed acyclic graph). When you make commits which are not associated with a branch, they are essentially inaccessible once you return to a known branch. If you make commits while you’re in a detached HEAD state, and then try to return to a known branch, Git will give you a warning and tell you how to save your work.

$ git checkout master

Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  7a85788 Your witty holiday commit message.

If you want to keep them by creating a new branch, this may be a good time to do so with:

$ git branch new_branch_name 7a85788

Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

So, if you want to save the commits you’ve made while in a detached HEAD state, you simply need to put them on a new branch.

$ git branch saved-headless-commits 7a85788

With this trick under your belt, you can jingle around in history as much as you’d like. It’s not like sliding around on a timeline though. When you checkout a specific commit, you will only have access to the history from that point backwards in time. If you want to move forward in history, you’ll need to move back to the branch tip by checking out the branch again.

$ git checkout helpful-boss-branch

You’re now back to the present. Your HEAD is now pointing to the endpoint of a known branch, and so it is no longer detached. Any changes you made while on your adventure are safely stored in a new branch, assuming you’ve followed the instructions Git gave you. That wasn’t so scary after all, now, was it?

Back to our reindeer problem.

If your boss is anything like the bosses I’ve worked with, chances are very good that at least some of their work is worth salvaging. Depending on how your repository is structured, you’ll want to capture the good work using one of several different methods.

Back in the living room, we’ll use our bowl of nuts to illustrate how you can rescue a tiny bit of work.

Saving just one commit

About that bowl of nuts. If you’re like me, you probably had some favourite kinds of nuts from an assorted collection. Walnuts were generally the most satisfying to crack open. So, instead of taking the entire bowl of nuts and dumping it into a stocking (merging the stocking and the bowl of nuts), we’re just going to pick out one nut from the bowl. In Git terms, we’re going to cherry-pick a commit and save it to another branch.

First, checkout the main branch for your development work. From this branch, create a new branch where you can copy the changes into.

$ git checkout master
$ git checkout -b rescue-the-boss

From your boss’s branch, helpful-boss-branch locate the commit you want to keep.

$ git log --oneline helpful-boss-branch

Let’s say the commit ID you want to keep is e08740b. From your rescue branch, use the command cherry-pick to copy the changes into your current branch.

$ git cherry-pick e08740b

If you review the history of your current branch again, you will see you now also have the changes made in the commit in your boss’s branch.

At this point you might need to make a few additional fixes to help your boss out. (You’re angling for a bonus out of all this. Go the extra mile.) Once you’ve made your additional changes, you’ll need to add that work to the branch as well.

$ git add [filename(s)]
$ git commit -m "Building on boss's work to improve feature X."

Go ahead and test everything, and make sure it’s perfect. You don’t want to introduce your own mistakes during the rescue mission!

Uploading the fixed branch

The next step is to upload the new branch to the remote repository so that your boss can download it and give you a huge bonus for helping you fix their branch.

$ git push -u origin rescue-the-boss

Cleaning up and getting back to work

With your boss rescued, and your bonus secured, you can now delete the local temporary branches.

$ git branch --delete rescue-the-boss
$ git branch --delete helpful-boss-branch

And settle back into your chair to wait for Saint Nicholas with your book, your branch, and possibly your cat.

$ git checkout waiting-for-st-nicholas
$ git stash pop

Your working directory has been returned to exactly the same state you were in at the beginning of the article.

Having fun with analogies

I’ve had a bit of fun with analogies in this article. But sometimes those little twists on ideas can really help someone pick up a new idea (git stash: it’s like when Christmas comes around and everyone throws their fashion sense out the window and puts on a reindeer sweater for the holiday party; or git bisect: it’s like trying to find that one broken light on the string of Christmas lights). It doesn’t matter if the analogy isn’t perfect. It’s just a way to give someone a temporary hook into a concept in a way that makes the concept accessible while the learner becomes comfortable with it. As the learner’s comfort increases, the analogies can drop away, making room for the technically correct definition of how something works.

Or, if you’re like me, you can choose to never grow old and just keep mucking about in the analogies. I’d argue it’s a lot more fun to play with a string of Christmas lights and some holiday cheer than a directed acyclic graph anyway.