How to Use git-blame?

When you are working on a shared codebase and need to find out who made a specific change, when it was made, and why, going through the entire commit history can be time-consuming. That’s where git blame comes in.

It helps you identify the author, date, and commit responsible for each line in a file. Whether you are fixing a bug, reviewing code, or understanding legacy logic, git blame gives you a quick way to track changes line by line. In this article, we will explore how git blame works and how to use it effectively in your workflow.

What is git-blame?

git blame is a Git command that annotates each line in a file with the following information:

• The last commit that modified the line.
• The author of the commit.
• The timestamp of the change.
• The line number and code content (optionally).

By using git blame, you can track the origin of each line of code, helping you understand the context of changes and who introduced them.

Why use git-blame?

Here are some common use cases:

• Debugging: When you encounter a bug, git blame helps you identify who last modified the affected lines, which can be a useful starting point.
• Code Reviews: Understand the history behind a line or section of code to get insights into why it exists.
• Collaboration: Know who to ask for clarification on a specific part of the codebase.

Syntax:

git blame [options] <file-name>

How to use git-blame?

Let's say in a git repository we have to identify the author details and commit information of a given line of code in a given file of the repository. The same is shown below. Let's walk through an example to understand the command.

Step 1: Move to an empty folder and initialize it with an empty git repository.

Step 2: Clone the repository for which you want the information. Here I am cloning a famous repository create-react-app from GitHub. Make sure to change the directory to the cloned repository.

Step 3: To get the author name and commit information, execute the git blame command as shown below. Replace the <file-name> option with the relative path of the file from the current directory for which you want details:

git blame <file-name>

Step 4: Here I want details for the file CONTRIBUTING.md which is present in the same directory I am currently at. So, I will execute the below command:

git blame CONTRIBUTING.md

Output:

Tip: Observe that the last column of output displays the line number along with the code on that line.

Output study

Let's examine the first line of output:

• Commit id: It is the commit Id of the last commit in which this line was modified. In upcoming lines, we will use it to get the details of the commit.
• Author Name: It is the name of the author who last modified the given line of code. We will see how to get the author's email id instead of the author's name.
• Timestamp: It is the date and time when the commit was made expressed in standard notation. We can get the raw timestamp using the -t option as shown below:

git blame -t CONTRIBUTING.md

Output is shown below:

Viewing the commit details: In order to view the commit details, we will execute the git log command with the commit id for which we want the details. So, copy the commit id from the previous output of the git blame command. In my case, I want the commit details for the first line of the CONTRIBUTING.md file, so I will copy the commit id from the previous output of the git blame command. The commit id for that is 46cf3fc43.

Now, execute the below command. Replace <commit-id> with the commit id that you copied just now.

git log -p <commit-id>

In my case the command is below:

git log -p 46cf3fc43

The git log command helps to view the commit history. The -p or --patch option shows the author details and changes (addition or deletion) in the code in the commit of commit id provided.

Options with git blame: Git provides various options with the git blame command for viewing the details of modification in code in a file. Some commonly used options are given below:

To view output for a range of lines

git blame -L start-line,end-line <file-name>

The below command shows output for lines 2 to 5 both inclusive.

git blame -L 2,5 CONTRIBUTING.md

The output is shown below:

Note: You will get the same output for command - git blame -L 4,+3 README.md. Here 4,+3 signifies output for 3 lines starting from the fourth line.

To view the author email id

git blame -e CONTRIBUTING.md

The above command will show the author's email id instead of the author's name in the result. The output is shown below:

To view changes not older than the given time

git blame --since=3.months-- CONTRIBUTING.md

The above command is used to view git blame output for commits not older than 3 months for the file CONTRIBUTING.md. The output is shown below:

In the above command, we can see that it shows several commits with commit id starting with ^. The caret symbols signify the commits made before the time specified, in our case, it is three months. Hence we need to filter out them from our output. To tackle that we can modify our code as below:

git blame --since=3.months -- CONTRIBUTING.md | grep -v '^\^'

The above code simply filters the output after removing commits starting with the ^ symbol. Hence, the output shows commits not older than three months (from the time the code is executed). The result is shown below:

An alternate option to the command line (GUI based): Git hosting sites like GitHub, Bitbucket, GitLab offer GUI displays for git blame, which gives a clear display of modification history in a file.

Example: GitHub

Step 1: Navigate to the file for which you want to see the modification history and click on the Blame option as shown below.

Step 2: The structure of output is described in the image below :

Hence, we saw that git blame is a very useful command in inspecting a repository. It gives a great insight into the commit history and can be used along with other git commands to get desired results.

Conclusion

In conclusion, git blame is a powerful command for tracing changes line by line. Whether you are debugging, reviewing code, or understanding historical context, git blame provides detailed insight into who changed what and when. It works well with both command-line and GUI interfaces like GitHub's "Blame" view, making it a go-to tool for collaborative and legacy code maintenance.