Table of Contents

TL;DR

This article explains how to use git log with the -G and -S options to track changes in your codebase more effectively.

  • -G searches for commits where lines matching a regex were modified (added or removed).

  • -S finds commits where the number of occurrences of a string changed (added or deleted).

  • Key difference: -G detects edits to matching lines; -S detects changes in the presence/absence of the pattern.

Why I wrote this

I needed to identify which tests I needed to perform for my PR, which changed the version of the Go runtime environment. Since there were several previous PRs with the details of the manual tests and other information I needed, I could search for another colleague's PR. However, there was a problem: how could I find a PR with this change among so many PRs and Cards? Manually it was not feasible.

Well, I immediately, already knowing a little about "git log", started looking for how I could find changes in the go.mod file that matched the regular expression ^go [0-9]. And voila, I found several PRs, rich in information that I needed :3

git log -G'^go [0-9]' -- go.mod

What is git log?

Before we delve into the specific options, let’s briefly understand what the git log command does. The git log command is used to display the commit history of a Git repository. It provides various options to filter and format this information, allowing developers to examine changes and understand the timeline of a project efficiently.

The -G Option: Searching for Changes in Code

The -G option allows you to look for changes in the commit history where the patch text (the differences made in the code) contains added or removed lines that match a specific regular expression.

How It Works

When you use -G, Git will scan the diffs of commits and show you only those that include lines added or removed that match your given regex pattern. This is especially useful when you are interested in a specific function, variable, or code pattern that may have undergone changes over time.

Example Use Case

Suppose you want to track the history of changes to a function called calculateSum. You can run:

git log -G'calculateSum'

This command will show you all commits that altered this function, along with the relevant diffs. It’s a powerful way to track how a particular piece of code has evolved throughout the project, allowing you to connect changes with specific commits.

The -S Option: Tracking Additions and Removals of Lines

In contrast, the -S option, often referred to as the "pickaxe" option, helps you find commits that specifically add or remove lines matching a given regex pattern. This means you’re interested not just in the changes themselves but in whether the number of occurrences of the specified string has changed.

How It Works
When you invoke the -S option, Git checks each commit to see if the number of occurrences of the specified string (or pattern) has increased or decreased. If the matches changed, it logs that commit, allowing you to understand when and why a particular pattern came into or out of use.

Example Use Case

If you want to see when the calculateSum function was added or removed entirely from the codebase, you can use:

git log -S'calculateSum'

This command will return commits that specifically dealt with the existence of that function, helping you identify when it was introduced or deleted.

Key Differences Between -G and -S

As illustrated in the original documentation excerpt, the primary distinction between these two options lies in what they track:

  • -G: Focuses on the content of the patch. It finds any modifications to the lines that match the regex.
  • -S: Concentrates on the count of occurrences. It will look for commits where the count of the matching string has changed.

For instance, if a function appears with a new name but has the same logic, -G may detect this change, whereas -S won't show a result since the string count hasn't changed.

Conclusion

As developers, mastering these tools can lead us to a deeper understanding of our projects, facilitate smarter debugging, and improve overall collaboration within teams. So go ahead, explore these options, and share your discoveries with fellow developers in your network!