So far we have always looked forwards: create the repository, stage changes, commit them, review the diff before recording it. This lesson turns the gaze around. We are going to query the past.

And this is where Git's real value lies. Storing versions is not much use if you cannot then answer questions like: when was this function introduced? Who touched styles.css last week, and why? In which commit did that line I could swear I wrote disappear? What was done on the project between Monday and Thursday?

git log answers all of them, but its default output is only the tip of the iceberg. It is an enormously configurable command: compact formats, graphs, per-file summaries, your own templates and a battery of filters that let you find one commit among thousands. In this lesson we will go through the whole of it, along with git show for inspecting a particular commit and the various ways of referring to a commit, which we have been using in passing (HEAD, HEAD~1) without fully explaining them.

1. Bruno's repository: our test bench
2. git log by default
3. Compact formats: --oneline and --graph
4. Seeing what changed: --stat and --patch
5. Custom formats with --pretty=format:
6. Filtering the history: count, dates, author and message
7. Filtering by path and the "pickaxe" search (-S and -G)
8. git show: inspecting a commit
9. How to refer to a commit
10. Useful combinations for everyday work

A few days have gone by since Bruno cloned the project. Ana already had four commits when he arrived, and since then Bruno has made three more in his own copy. This is the history sitting on his MacBook:

Seven commits: Ana's four, which arrived with the clone, and the three Bruno has made locally. Notice (origin/main): it marks where the server stood when Bruno cloned. His three commits sit ahead of that mark because he has not pushed them yet; that is the business of module 4.

This mixed history will serve us well: it has two authors, different dates and changes to different files, which is exactly what we need to practise the filters.

(The output carries on; you leave the pager with q.)

Each entry has four elements:

A couple of important points:

• The order is reverse chronological: newest at the top. That is what you want 95% of the time. --reverse flips it.
• Author and Committer are different fields. Remember from the data model that a commit stores both. Normally they coincide and git log shows only the first; they part company when somebody applies a patch written by another person, or on a rebase. To see both:

• git log only shows the history reachable from where you are. By default it starts at HEAD and follows the links to the parents. Commits living on other branches do not appear unless you ask for them explicitly or use --all.

One line per commit: abbreviated hash, the references pointing there and the first line of the message. It is the most used format, and it explains why that first line has to work on its own: in this view it is all you see.

--oneline is in fact shorthand for --pretty=oneline --abbrev-commit.

It draws the commit graph with text characters:

With a single line of development, the graph is a column of asterisks and adds little. Its value appears once there are branches and merges, where it shows the forks and the joining points:

That is what the team's history will look like from module 3 onwards. To see the graph of all branches, not just the current one:

--decorate shows the references (branches, tags, HEAD) next to each commit. In modern Git it is on by default in the terminal, but it is worth knowing about.

It is the most useful view for getting a quick sense of the size and reach of each change without reading the code. Variants:

It shows the history with the diff of every commit, in the unified diff format you learned to read in the previous lesson. It is the most thorough way of reviewing work, and also the longest: always use it with a limit (-1, -5) or combined with a filter.

One particularly valuable combination:

It shows the complete evolution of a single file, commit by commit, with each one's diff. It is like watching a film of the file from birth onwards.

When none of the predefined formats fits, you can design your own with a template:

The placeholders start with %. These are the ones that actually get used:

The %C... placeholders control colour and make the output far more readable:

Available colours: red, green, yellow, blue, magenta, cyan, white, and %C(auto) to let Git decide. %C(reset) returns to the normal colour, and %C(bold …) gives bold.

This template is a classic and deserves saving as an alias:

Aliases are stored in ~/.gitconfig through the mechanism we saw in Configuring Git, and they are covered in depth in Git Log and Aliases.

On a two-year-old project, git log returns thousands of entries. The filters are what turn the command into a search tool.

Git also takes natural-language expressions, which is very convenient:

The value is a regular expression matched against both the name and the e-mail, so a fragment is enough:

And the symmetrical filter for the committer:

This is a regular expression too, and by default it is case-sensitive. To ignore case:

Several --grep options combine with a logical OR by default; --all-match turns them into an AND:

And watch out for this: when you combine filters of different kinds, they apply with a logical AND:

Commits by Bruno, from 30 July onwards, whose message contains "style". Just the one.

Only the commits that modified that file. As in git diff, the -- separates options from paths and is mandatory when the name could be confused with a branch.

It takes directories and patterns:

Combined with -p, it is the best way of understanding how a file came to be what it is:

--follow tracks the file across renames. Without it, the history would stop dead at the moment the file changed name. It only works with one file at a time.

Here comes one of Git's most useful and least known abilities. -S finds the commits in which the number of occurrences of a string changed. In practice: when that text was introduced or removed.

A single commit: the one where the function appeared. If somebody deleted it later, that commit would show up too.

Compare it with --grep, which is a completely different thing:

The star use case for -S is this: you find an odd line in the code, you want to know why it is there, and git blame only tells you who touched it last. With -S you find the original commit that introduced it, with its explanatory message.

It shows the commit where that CSS declaration appeared, with its diff. Surgical searching.

To see it in more detail:

The difference from -S is subtle but important:

• -S "text" finds the commits where the number of times that text appears changed. If you move a line elsewhere within the same file, the count does not change and -S does not find it.
• -G "regex" finds every commit whose diff contains an added or removed line matching the expression. A move does show up.

A practical rule: -S for "when was this introduced?"; -G for "which commits touched something like this?".

Both accept --pickaxe-regex and combine with every other filter:

Once you have located the commit you are after, git show displays it in full:

Metadata and diff in a single view. It is equivalent to git log -p -1 <commit>, but more direct.

git show is more versatile than it looks, because it accepts any Git object:

The <commit>:<path> syntax is especially handy. We already used it earlier in the module to check which version of a file had been recorded. It serves, for example, to recover an old version without disturbing anything else:

And combined with -s and a format, git show is a way of extracting specific data:

We have been using HEAD, HEAD~1 and hashes without ever setting the notation out systematically. Let us close that gap, because it turns up in practically every Git command.

An unambiguous prefix is all you need. Git requires at least 4 characters and uses 7 by default when displaying them. In very large repositories you may need a few more; if the prefix is ambiguous, Git tells you:

These two are the confusing pair, and the difference only matters when there are merges (commits with more than one parent):

In short:

• ~ walks back through generations along the main line. ~3 = three steps back.
• ^ chooses between the parents of one commit. ^2 = the second parent.

In a linear history like Bruno's, HEAD~2 and HEAD^^ are exactly the same thing:

The diagram makes it plain:

The arrows point backwards because that is how Git works: each commit knows its parent, not its children. That is why walking the history into the past is easy and there is no simple notation for going forwards.

And once there are merges (module 3), ^ will come into its own:

Two dots define a range of commits:

Read it as "the commits reachable from c5d9b1e but not from 8b6d3c2". That is: everything after 8b6d3c2 up to and including c5d9b1e. Note that the left-hand end is left out.

Much used forms:

That second-to-last one is exactly what Bruno has waiting to be pushed:

His three local commits. All of this is developed in module 4.

git rev-parse translates any notation into a full hash, and it is the way to settle any doubt:

A recipe book of queries that answer real questions:

And a practical warning: git log opens a pager. You move through it with the arrow keys or the space bar, search with /text and leave with q. If you prefer the output straight:

• Confusing --grep with -S. --grep searches the commit message; -S searches the content of the files. They are completely different questions, and it is the commonest mistake when searching the history.
• Forgetting the -- before a path. git log styles.css works when there is no ambiguity, but git log main will read main as a branch. Put -- in whenever there is room for doubt.
• Expecting git log to show every branch. By default it only walks the history reachable from HEAD. To see the lot, --all.
• Misreading a..b ranges. The left-hand end is not included. git log HEAD~3..HEAD returns three commits, not four.
• Using ~ when you want ^. In a linear history they are interchangeable, but on a merge HEAD^2 (the second parent) and HEAD~2 (two generations back) point to different places.
• Getting stuck in the pager. You leave with q. It is one of everybody's first frustrations with Git.
• Scanning git log -p by eye. If you are looking for where a particular piece of text appeared, -S hands it to you in one command instead of making you read a hundred diffs.
• Not using --follow when looking at the history of a renamed file. You will see a history that "starts" at the rename and wrongly conclude that the file is recent.
• Tip: define the lg alias from section 5. You will use it daily and it makes the history far more readable.
• Tip: git shortlog -sn is the quickest way of learning who works on a project you have just cloned. And git log --oneline -20 gives you the pulse of what is being done right now.
• Tip: if you want to export the history for a report, --pretty=format: combined with --date=short produces lines any spreadsheet can process.

Starting from Bruno's history as it appears in section 1:

Write the exact command for each query and predict its output:

1. The last three commits, one line each.
2. All of Ana's commits.
3. Everything done between 23 and 27 July, both included.
4. The commits that touched styles.css.
5. The commits whose message contains "task", ignoring case.
6. A listing formatted as hash | short date | author | subject.
7. How many commits there are in total and how many each person has made.
8. The contents of README.md as they stood at 4e7f2a9.

Create a repository with a history in which a line appears, moves and vanishes:

1. What does git log --oneline -S "DEBUGGING" return? Explain why each commit appears and why one is missing.
2. What does git log --oneline -G "DEBUGGING" return? Compare it with the previous result and explain the difference.
3. What does git log --oneline --grep="DEBUGGING" return? And --grep="debug"?
4. Write the command that shows the diff of the exact commit where the trace was removed.
5. Write, in one sentence, the rule that will let you choose between -S, -G and --grep in future.

Working on the repository from exercise 2 (four commits, a linear history):

1. Write four different ways of referring to the second commit in the history (the one that added the trace).
2. Check with git rev-parse that HEAD~2 and HEAD^^ point at the same object.
3. Show the contents of app.js as they stood at the first commit, without modifying your working tree.
4. Show only the messages of the last two commits, with no diff.
5. Use a range to list only the last two commits and explain why HEAD~2..HEAD returns two and not three.
6. Find out which files each of the four commits modified, with a single command.

Solution to Exercise 1

1. The last three:

2. Ana's:

3. Between the 23rd and the 27th, both included:

Mind the detail: --until="2026-07-27" is read as 00:00 on that day, so it would exclude the commits made on the 27th itself. Since we want the whole of the 27th included, we write --until="2026-07-28". It is a classic mistake that makes commits on the last day of the range "disappear".

4. The ones that touched styles.css:

A note: 1a4c8d6 created the file, so in a real history it would appear as well. The exercise states that the initial commit contained all four files, so the complete output would have three entries.

5. Messages containing "task", ignoring case:

Five of the seven. Left out are c5d9b1e ("Document installation in the README") and 8b6d3c2 ("Add base styles for the list"), whose messages do not contain the word.

6. A custom format:

7. Totals:

8. The README at 4e7f2a9:

It prints the contents of the file as they stood at that commit, without touching the working tree. If we wanted to save it separately:

Solution to Exercise 2

1. With -S:

Two commits. -S looks for changes in the number of occurrences of the string:

• 9b3e5d7: went from 0 occurrences to 1. It changed → it appears.
• 1f4c8a2: went from 1 to 0. It changed → it appears.

Missing is 7a2d6f9 ("Move the trace to the new end function"). And here is the nuance to grasp: in that commit the trace moved from start() to end(), so it still appears exactly once. Since the count does not vary (1 → 1), -S treats it as irrelevant and does not show it.

2. With -G:

Three commits. -G does not count occurrences: it checks whether the commit's diff contains an added or removed line matching the expression. In 7a2d6f9 there is one line with DEBUGGING removed and another added, so it does appear.

That is exactly the difference between the two options, and the exercise isolates it in its purest form.

3. With --grep:

None, because --grep searches the message, and no message contains the word in capitals.

Two: the ones carrying that word in the message. That they coincide with the -S result is pure chance in this example; it happens because the messages describe well what they do.

4. The diff of the removal:

Or, more directly and more readably, locate the commit and show it:

A robust way of chaining it, without knowing the hash in advance:

which shows the most recent commit in which the count of that string changed: precisely the removal.

5. The rule:

--grep searches the message ("who said they did this?"); -S finds when a piece of text appeared or disappeared in the code ("where did this line come from?"); -G finds which commits touched lines matching a pattern, moves included ("who has been in here?").

Solution to Exercise 3

1. Four ways of referring to the second commit (with HEAD on the fourth):

And there are more: the full hash, main~2, @~2… They all resolve to the same object.

2. Checking:

Identical hashes. In a linear history, ~n and n ^ symbols are equivalent, because each commit has a single parent and "pick the first parent" and "go back one generation" are the same operation. The difference only emerges on merges.

3. The file at the first commit:

git show <commit>:<path> reads from the history and writes to standard output. It changes nothing, unlike git restore --source=..., which would overwrite the file on disk.

4. The messages of the last two only:

Or, if you prefer the full view without the diff:

5. The range:

Two commits, not three, because the left-hand end of the range is excluded. a..b means "everything reachable from b that is not reachable from a", and HEAD~2 is reachable from itself, so it is discarded. The way to read it is: "what has happened after HEAD~2".

If you wanted HEAD~2 included as well, you would have to write HEAD~3..HEAD.

6. Files modified by each commit:

The last three commits modify app.js (M) and the first one adds it (A), which is consistent: it was the root-commit and the file did not exist before.

This lesson closes Git's basic cycle and module 2. Recapping what we covered here:

• git log walks the history backwards from HEAD, in reverse chronological order, following the links to the parents.
• The formats change completely what you see: --oneline for the working view, --graph for the structure (essential as soon as there are branches), --stat for the reach of each change and -p for the full diff.
• --pretty=format: lets you design your own output with placeholders such as %h, %an, %ar and %s, and it is worth saving as an alias.
• The filters turn git log into a search engine: -n by count, --since/--until by date, --author by person, --grep by message and -- <path> by file. Filters of different kinds combine with a logical AND.
• The "pickaxe" search is the hidden gem: -S finds when a piece of text appeared or disappeared in the code, and -G which commits touched lines matching a pattern. Do not confuse either of them with --grep, which looks at the message.
• git show inspects one particular commit — metadata and diff — and with the <commit>:<path> syntax it recovers any file exactly as it stood at any moment in the past.
• Referring to a commit can be done by hash (full or abbreviated), by symbolic reference (HEAD, main, origin/main, a tag) or by relative navigation: ~ goes back generations and ^ chooses between parents. Ranges a..b exclude the left-hand end.

You have been through the complete cycle of working with Git on your own:

1. Creating the repository (git init) or joining an existing one (git clone).
2. Working through the edit → stage → commit cycle, with git status as your compass.
3. Choosing precisely what goes into each commit, right down to hunk level with git add -p.
4. Reviewing the changes with git diff before recording them.
5. Querying the past with git log and git show.

With this you can already use Git productively on any project of your own. But there is a problem waiting.

Look at the real situation Ana and Bruno are in right now. Both of them have been working on main, each on their own laptop, with no coordination. Ana has added the task counter and the marking of completed tasks; Bruno has added the pending filter and touched the same files. Neither has seen the other's work.

When they try to bring all of that together, they will find two different versions of app.js that have evolved separately from the same starting point. And this is with only two people and a week's work: once Carla joins from Windows and there are three simultaneous lines of development, everybody working on main will be untenable.

There is a subtler problem too. Right now, if Ana wants to try a risky idea, she has nowhere to do it: anything she commits goes straight into the project's only line. And if a critical bug turns up halfway through an urgent task, she has to abandon what she is doing or commit it half finished.

The answer to all of this is branches, and they are the feature that made Git the industry standard. In module 3: Branching and Merging we will see what a branch really is (spoiler: you already know, it is a file with a hash inside, as we saw when creating the first commit), how to create them and move between them, how to merge several people's work, what strategies Git uses to do so, how to resolve conflicts when two people touch the same line, and how to keep a repository with many live branches in order.

Everything you have learned in this module — the three areas, the staging area, the diff, the history — remains valid exactly as it is. It is just that from now on there will be more than one line of work at a time.