You’re happily working your way through a codebase when you happen upon some code that makes you stop and think: What the…!? Maybe it’s a method that’s doing something surprising. Or perhaps it’s doing something completely unsurprising, it’s just doing it in a surprising way.
Git blame to the rescue?
When this happens you might instinctively reach for
git blame to help you figure out what’s going on. After all,
git blame gives you the commit that most recently touched the line, and often that’s enough to point you in the right direction. But often it isn’t and you’re none the wiser. That’s because:
- git blame is too coarse: it reports against the whole line. If the most recent change isn’t related to the part of the line you’re interested, you’re out of luck.
- git blame is too shallow: it only reports a single change; the most recent one. The story of the particular piece of code you’re interested in may have evolved over several commits.
- git blame is too narrow: it only considers the file you are running blame against. The code you are interested in may also appear in other files, but to get the relevant commits on those you’ll need to run blame several times.
If you only use
git blame you’re limiting yourself to a one-dimensional perspective of the code you’re trying to understand. Wouldn’t it be better to view things in 3D!?
A more powerful way to trace the history of WTF code
Thankfully Git has some pretty powerful search tools built right in. Let’s take a closer look at some of the tools at our disposal.
Find all commits containing a particular piece code
git blame is entry-level history search,
git log -S (also known as “the pickaxe”) is how you take things to the next level. It lets you search for all commits that contain a given string:
$ git log -S "method_name"
This will return all the commits that contain
method_name across the entire repository, giving you a bespoke history of a piece of code across both multiple commits and files. You can use the pickaxe to examine the entire history of a particular snippet: all the places it’s been used; how it’s usage has changed; if it’s moved file; when it was first introduced, and more.
See the diffs alongside the commit messages
If you include the
-p option (short for
--patch) you get the full diff alongside the commit messages, giving you even more context and making it easier to spot the relevant changes:
$ git log -S "method_name" -p
Find the commit that first added some code
Say you want to find the first commit that introduced a particular class, method or snippet of code. You can use the pickaxe combined with the
--reverse option to get the commits in reverse-chronological order so the commit where the code first appears is listed at the top:
$ git log -S "method_name" -p --reverse
Find when a piece of code was deleted
Because the pickaxe search finds both additions and deletions, you can even use it to find code that has since been deleted:
$ git log -S "deleted code" -p
Assuming the snippet no longer exists in the codebase the first commit returned will be the one where it was removed.
Limit the scope of the search
Because we’re using
git log you can also provide a path to focus the search to a given file or folder:
$ git log -S "some code" -p app/models/user.rb
Search deeper with a regular expression
I mostly stick to the pickaxe because I find working with regular expressions cumbersome, but if you want to perform a more advanced search using a regular expression you can do so with
$ git log -G "REGEX HERE"
It’s also worth noting that searching with
-S has a subtle limitation that
-G does not:
-S only shows commits that either added or removed the search string. If the string you are searching for moved within the same file but was otherwise unchanged,
-S won’t include that commit, whereas
Search the commit messages themselves
Sometimes searching for literal code is too narrow, or the information you’re after isn’t actually in the code but in the commit messages themselves. In which case you can use
--grep to search commit messages instead:
$ git log --grep "commit message search"
Next time some code has you puzzled and you want to understand more about it, look beyond
git blame and dig deeper into the history using the pickaxe and friends:
- Find the entire history of a snippet of code with
git log -S
-pto see the diff as well as the commit messages
--reverseto see the commit that introduced the code listed first
- Scope search to specific folders or files by including a path
- Search with a regular expression using
git log -G
- Search commit messages using
git log --grep
Of course searching a codebase’s history will only be fruitful if the history itself is helpful. If the history hasn’t been constructed with atomic commits that have useful commit messages, searching it will likely be a frustrating and unhelpful experience.
To learn more about the how and why of putting together more useful histories, check out A Branch in Time (a talk about revision histories).
More articles on Git