Skip to content

Exploring History

Objectives

  • Explain what the HEAD of a repository is and how to use it.
  • Identify and use Git commit numbers.
  • Compare various versions of tracked files.
  • Restore old versions of files.

Questions

  • How can I identify old versions of files?
  • How do I review my changes?
  • How can I recover old versions of files?

In this section, we’ll explore how we can use git to work with the version history. To start, let’s take a quick look at what we’ve done so far: 

git log

Paging the Log

When the output of git log is too long to fit in your screen, git uses a program to split it into pages of the size of your screen. When this "pager" is called, you will notice that the last line in your screen is a :, instead of your usual prompt.

  • To get out of the pager, press Q.
  • To move to the next page, press Spacebar.
  • To search for some_word in all pages, press / and type some_word. Navigate through matches pressing n (or N to go back).

Limit Log Size

To avoid having git log cover your entire terminal screen, you can limit the number of commits that Git lists by using -N, where N is the number of commits that you want to view. For example, if you only want information from the last commit you can use:

$ git log -1

commit 645101c0fa78ab03ab2ac087f3e1b4eaff85d454 (HEAD -> main, origin/main, origin/HEAD)
Author: Jost Migenda
Date:   Mon May 19 17:17:02 2025 +0100

add analysis scripts

You can also reduce the quantity of information using the --oneline option:

$ git log --oneline

645101c (HEAD -> main, origin/main, origin/HEAD) add analysis scripts
5cc6641 Modify README
5921689 add details to README
18898b0 Add initial version of README
c9ef82f Initial commit

As we saw in the previous episode, we can refer to commits by their identifiers. You can refer to the most recent commit of the working directory by using the identifier HEAD.

We've been adding small changes at a time to README, so it's easy to track our progress by looking, so let's do that using our HEADs. Before we start, let's make a change to README, adding yet another line.

$ nano README

Now, let's see what we get.

$ git diff HEAD README

diff --git a/README b/README
index 18f7ceb..5280482 100644
--- a/README
+++ b/README
@@ -6,3 +6,5 @@ N.B. you will need to install the "imagecodecs" package.
 This is a modified line!

 The `scripts/` directory contains our analysis scripts.
+
+An ill-considered change

Note that HEAD is the default option for git diff, so omitting it will not change the command's output at all (give it a try). However, the real power of git diff lies in its ability to compare with previous commits. For example, by adding ~1 (where "~" is "tilde", pronounced [til-duh]), we can look at the commit before HEAD.

$ git diff HEAD~1 README

If we want to see the differences between older commits we can use git diff again, but with the notation HEAD~1, HEAD~2, and so on, to refer to them:

$ git diff HEAD~2 README

diff --git a/README b/README
index 3c196e8..5280482 100644
--- a/README
+++ b/README
@@ -3,4 +3,8 @@ First run the "process_images" script and then the "analyse_images" script.

 N.B. you will need to install the "imagecodecs" package.

-This is an added line!
+This is a modified line!
+
+The `scripts/` directory contains our analysis scripts.
+
+An ill-considered change

We could also use git show which shows us what changes we made at an older commit as well as the commit message, rather than the differences between a commit and our working directory that we see by using git diff.

$ git show HEAD~1 README

commit 5cc664186d6ba95a2476c1e5c30c17e01d73c751
Author: Jost Migenda
Date:   Mon May 19 16:56:20 2025 +0100

    Modify README

diff --git a/README b/README
index 3c196e8..423cdd4 100644
--- a/README
+++ b/README
@@ -3,4 +3,4 @@ First run the "process_images" script and then the "analyse_images" script.

 N.B. you will need to install the "imagecodecs" package.

-This is an added line!
+This is a modified line!

In this way, we can build up a chain of commits. The most recent end of the chain is referred to as HEAD; we can refer to previous commits using the ~ notation, so HEAD~1 means "the previous commit", while HEAD~123 goes back 123 commits from where we are now.

We can also refer to commits using those long strings of digits and letters that both git log and git show display. These are unique IDs for the changes, and "unique" really does mean unique: every change to any set of files on any computer has a unique 40-character identifier. One of our recent commits was given the ID 5921689e37c8ff667c7a84ab6e8feb652237ad14, so let's try this:

$ git diff 5921689e37c8ff667c7a84ab6e8feb652237ad14 README

diff --git a/README b/README
index 3c196e8..5280482 100644
--- a/README
+++ b/README
@@ -3,4 +3,8 @@ First run the "process_images" script and then the "analyse_images" script.

 N.B. you will need to install the "imagecodecs" package.

-This is an added line!
+This is a modified line!
+
+The `scripts/` directory contains our analysis scripts.
+
+An ill-considered change

That's the right answer, but typing out random 40-character strings is annoying, so Git lets us use just the first few characters (typically seven for normal size projects):

$ git diff 5921689 README

All right! So we can save changes to files and see what we've changed. Now, how can we restore older versions of things? Let's suppose we change our mind about the last update to README (the "ill-considered change").

git status now tells us that the file has been changed, but those changes haven't been staged:

$ git status

On branch main
Your branch is up-to-date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README

no changes added to commit (use "git add" and/or "git commit -a")

We can put things back the way they were by using git restore:

$ git restore README
$ cat README

As you might guess from its name, git restore restores an old version of a file. By default, it recovers the version of the file recorded in HEAD, which is the last saved commit. If we want to go back even further, we can use a commit identifier instead, using -s option:

$ git restore -s 5921689 README

$ cat README
$ git status

On branch main
Your branch is up-to-date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   README

no changes added to commit (use "git add" and/or "git commit -a")

Notice that the changes are not currently in the staging area, and have not been committed. If we wished, we can put things back the way they were at the last commit by using git restore to overwrite the working copy with the last committed version:

$ git restore README
$ cat README

It's important to remember that we must use the commit number that identifies the state of the repository before the change we're trying to undo. A common mistake is to use the number of the commit in which we made the change we're trying to discard. In the example below, we want to retrieve the state from before the most recent commit (HEAD~1), which is commit f22b25e. We use the . to mean all files:

A diagram showing how git restore can be used to restore the previous version of two files

So, to put it all together, here's how Git works in cartoon form:

A diagram showing the entire git workflow: local changes are staged using git add, applied to the local repository using git commit, and can be restored from the repository using git checkout

The fact that files can be reverted one by one tends to change the way people organize their work. If everything is in one large script file, it's hard (but not impossible) to undo changes to one part of the code without also undoing changes made later to other parts. If independent parts of the code are stored in separate files, on the other hand, moving backward and forward in time becomes much easier.

Recovering Older Versions of a File

Jennifer has made changes to the Python script that she has been working on for weeks, and the modifications she made this morning "broke" the script and it no longer runs. She has spent about an hour trying to fix it, with no luck …

Luckily, she has been keeping track of her project's versions using Git! Which commands below will let her recover the last committed version of her Python script called data_cruncher.py?

  1. $ git restore

  2. $ git restore data_cruncher.py

  3. $ git restore -s HEAD~1 data_cruncher.py

  4. $ git restore -s <unique ID of last commit> data_cruncher.py

  5. Both 2 and 4

Solution

The answer is number 5 (“Both 2 and 4”).

The restore command restores files from the repository, overwriting the files in your working directory. Answers 2 and 4 both restore the latest version in the repository of the file data_cruncher.py. Answer 2 uses HEAD to indicate the latest, whereas answer 4 uses the unique ID of the last commit, which is what HEAD means.

Answer 3 gets the version of data_cruncher.py from the commit before HEAD, which is NOT what we wanted.

Answer 1 results in an error. You need to specify a file to restore. If you want to restore all files you should use git restore .

Reverting a Commit

Jennifer is collaborating with colleagues on her Python script. She realizes her last commit to the project's repository contained an error, and wants to undo it. Jennifer wants to undo correctly so everyone in the project's repository gets the correct change. The command git revert [erroneous commit ID] will create a new commit that reverses the erroneous commit.

The command git revert is different from git restore -s [commit ID] . because git restore returns the files not yet committed within the local repository to a previous state, whereas git revert reverses changes committed to the local and project repositories.

Below are the right steps and explanations for Jennifer to use git revert, what is the missing command?

  1. ________ # Look at the git history of the project to find the commit ID

  2. Copy the ID (the first few characters of the ID, e.g. 0b1d055).

  3. git revert [commit ID]

  4. Type in the new commit message.

  5. Save and close.

Solution

The command git log lists project history with commit IDs.

The command git show HEAD shows changes made at the latest commit, and lists the commit ID; however, Jennifer should double-check it is the correct commit, and no one else has committed changes to the repository.

Checking Understanding of git diff

Consider this command: git diff HEAD~9 README. What do you predict this command will do if you execute it? What happens when you do execute it? Why?

Try another command, git diff [ID] README, where [ID] is replaced with the unique identifier for your most recent commit. What do you think will happen, and what does happen?

Getting Rid of Staged Changes

git restore can be used to restore a previous commit when unstaged changes have been made, but will it also work for changes that have been staged but not committed? Make a change to README, add that change using git add, then use git restore to see if you can remove your change.

Solution

After adding a change, git restore can not be used directly. Let's look at the output of git status:

On branch main
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
        modified:   README

Note that if you don't have the same output you may either have forgotten to change the file, or you have added it and committed it.

Using the command git restore README now does not give an error, but it does not restore the file either. Git helpfully tells us that we need to use git restore --staged first to unstage the file:

$ git restore --staged README

Now, git status gives us:

$ git status

On branch main
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git git restore <file>..." to discard changes in working directory)
        modified:   README

no changes added to commit (use "git add" and/or "git commit -a")

This means we can now use git restore to restore the file to the previous commit:

$ git restore README
$ git status

On branch main
nothing to commit, working tree clean

Explore and Summarize Histories

Exploring history is an important part of Git, and often it is a challenge to find the right commit ID, especially if the commit is from several months ago.

Imagine your project has more than 50 files. You would like to find a commit that modifies some specific text in the README. When you type git log, a very long list appeared. How can you narrow down the search?

Recall that the git diff command allows us to explore one specific file, e.g., git diff README. We can apply a similar idea here.

$ git log README

Unfortunately some of these commit messages are very ambiguous, e.g., update files. How can you search through these files?

Both git diff and git log are very useful and they summarize a different part of the history for you. Is it possible to combine both? Let's try the following:

$ git log --patch README

You should get a long list of output, and you should be able to see both commit messages and the difference between each commit.

Question: What does the following command do?

$ git log --patch HEAD~9 *.py

Finally, since we’ve reached the end of a section, let’s make sure all our changes are saved and backed up to the remote repository: 

git status
git push origin

Keypoints

  • git diff displays differences between commits.
  • git restore recovers old versions of files.
  • HEAD always refers to the latest commit, HEAD~1 refers to the commit before that, etc.