Git Blame & Auditing
In Git, blaming and auditing means inspecting a file's history to understand who last modified each line, when the change occurred, and which commit introduced it.
This is useful for debugging, investigating regressions, reviewing code changes, and understanding the context behind implementation decisions.
git blame helps identify the commit
associated with a line. Use git show
and git log to investigate the
surrounding changes and commit messages.
1. The Basic Git Blame
Use the following command to inspect the history of individual lines in a file.
git blame filename.ext
The output typically shows:
- Commit hash: Identifies the commit associated with the line.
- Author: Shows the recorded author of the change.
- Timestamp: Indicates when the change was made.
- Source line: Displays the corresponding line of code.
Replace filename.ext with the actual
file path, such as src/LoginController.cs.
2. Narrowing Down the Search
Blame Specific Lines
Use the -L option to inspect a specific
range of lines instead of the entire file.
git blame -L 15,30 filename.ext
This displays blame information for lines 15 through 30.
Ignore Whitespace Changes
Use the -w option to ignore whitespace
changes when identifying the origin of lines.
git blame -w filename.ext
This can help when a commit changed indentation or formatting without changing the underlying logic.
3. Deep Auditing with Git Log
After finding a commit hash with
git blame, investigate the commit
to understand what changed and why.
View Commit Details and Changes
git show <commit-hash>
Displays information about the commit, including its message and the changes introduced by it.
Search History for a String
git log -S "functionName" --oneline
The -S option searches for commits
where the number of occurrences of the specified
string changes. It can help identify when a
function name or text was introduced or removed.
View a File's Commit History
git log --oneline -- filename.ext
Lists commits affecting the specified file.
4. Graphical Auditing Tools
Visual Studio Code with GitLens
GitLens can display Git blame annotations inside Visual Studio Code. These annotations help you inspect line authorship and related commit details without repeatedly running terminal commands.
GitHub Web Interface
To inspect blame information on GitHub:
- Open your repository on GitHub.
- Navigate to the file you want to inspect.
- Open the file's Blame view.
- Review the associated commits and line changes.
- Open a commit to examine its message and diff.
The blame view is useful when you want to audit a file without checking out the repository locally.
5. Example: Investigate a Bug
Suppose a method started behaving incorrectly after a recent code change. You can trace its history with the following workflow.
Step 1: Inspect the Relevant Lines
git blame -L 20,40 src/LoginController.cs
Step 2: Inspect the Suspected Commit
git show <commit-hash>
Step 3: Review the File's History
git log --oneline -- src/LoginController.cs
Together, these commands help you identify the relevant change and understand the context before deciding how to fix the issue.
6. Quick Reference
| Command | Purpose |
|---|---|
git blame filename.ext |
Inspect line-by-line authorship and commit information. |
git blame -L 15,30 filename.ext |
Inspect a specific range of lines. |
git blame -w filename.ext |
Ignore whitespace changes during blame analysis. |
git show <commit-hash> |
Inspect a commit and its changes. |
git log -S "functionName" --oneline |
Find commits that change the occurrence count of a string. |
git log --oneline -- filename.ext |
View the commit history of a file. |
git blame to trace individual lines,
git show to inspect a particular commit,
and git log to explore the broader
history of a file or code change.