Carla has already fixed task deletion thanks to bisect. But while she was in app.js she came across this:

Nobody on the team remembers writing that function. It is not documented, it has no comments and it looks like a defensive patch against something very specific. The temptation to delete it is enormous: it is five lines that "do nothing".

That temptation is exactly the scenario described by Chesterton's fence: do not take down a fence in the middle of a field until you know why it was put there. And in a Git repository you can always find out, because every line of every file comes from a specific commit, with its author, its date and its message.

The tool that makes that query is git blame, and in this lesson we are going to squeeze it dry: not just to see who touched the line last, but to see through the noise — reformatting, moved code, spacing changes — and get to the commit that really explains the why.

1. What git blame is exactly
2. Reading the output
3. Narrowing down: -L by lines and by function
4. Seeing beyond the noise: -w, -M and -C
5. Travelling in time: <sha>^ and --since
6. git log -L: the complete evolution of a range of lines
7. Ignoring formatting commits: --ignore-rev and .git-blame-ignore-revs
8. Solving the normaliseText mystery
9. Blame in practice: attribution, not fault

git blame <file> answers a very specific question:

For each line of the file as it stands now, what was the last commit that modified it?

Three things in that definition are worth underlining, because the three most common misunderstandings come from there:

• It is "the last one that touched it", not "the one that wrote it". If Ana wrote the line in January and Bruno changed a comma in June, blame points at Bruno. Sections 4 and 7 are precisely the tools for seeing through that noise.
• It works on the file's current state. Deleted lines do not appear: if you are interested in those, the tool is git log -L (section 6) or the -S pickaxe from lesson 02-06.
• It computes nothing new. All the information is already in the data model from lesson 01-04: blame walks the file's history comparing versions and attributes each line. It is a query, not stored metadata.

The five columns, from left to right:

And two special markers that you need to know how to read:

• ^7d2a1f8, with a caret: the line comes from the oldest commit in the analysed range. It is usually the initial commit (boundary commit). It means "this is as old as the history I am looking at".
• 00000000 / Not Committed Yet: the line is modified in the working tree and has not been committed yet. It is yours, right now.

Formatting options that save a lot of time:

And the one really used day to day, because it combines just the right things:

One practical detail: blame's output is long and usually goes through the pager. To jump straight to the area you care about, in less all you need is /normaliseText + Enter. But it is far better to narrow down from the start, which is what comes next.

You almost never want the whole file. -L limits the analysis to a range:

Ways of expressing the range, all valid:

The -L :<name>:<file> form is the most convenient and the least known. Git locates the function's block using the same funcname rules that git diff uses for hunk headers (lesson 02-05):

First clue in the mystery: the function was created by Carla in February, and Ana added the two replace calls in May. Two commits, two possibly different reasons.

Function recognition depends on the language. Git ships built-in patterns for many of them (c, java, python, php, rust…). For JavaScript, the built-in javascript pattern is activated by declaring it in .gitattributes with *.js diff=javascript. That file, and everything it lets you configure, is the subject of lesson 08-04; here it is enough to know that if -L :function: misses, that is the reason.

Here is blame's real value, and what separates naive use from expert use. "Raw" attribution lies constantly, because:

• Somebody reindented the file → every line is theirs.
• Somebody moved a function elsewhere within the same file → every line is theirs.
• Somebody extracted a module into a new file → every line is theirs.

In all three cases, the content did not change, and blame is pointing at the messenger. These three options correct it:

It ignores differences that are only whitespace when comparing versions. If Bruno ran the file through the formatter and changed the indentation from 4 spaces to 2, -w looks through that commit and carries on attributing the line to whoever wrote the actual code.

It is practically free and almost never gets in the way. Always use it.

It detects blocks of lines that were moved or copied within the same file and attributes the line to its origin, not to the commit that moved it. This is the "I have reordered the functions to group the storage ones together" case.

It detects lines that come from another file modified in the same commit. This is the case of extracting code into a new module.

-C has levels, according to how many times it is repeated, and this is the table to keep to hand:

And the detection threshold can be tuned with a number: -M20 requires at least 20 alphanumeric characters before considering that a block was moved (the default for -M is 40).

In practice, the invocation that solves 95% of serious investigations is:

Note that everything can be combined: ignore whitespace, follow moves between files at a medium-high level, and narrow down to a function. It is slower, but in a file of a few hundred lines you do not even notice.

A practical comparison of the effect, on the same lines:

The first result points at Bruno and at a July commit: that is the commit in which Bruno moved the function from index.html to app.js. Informationally, it is useless. The second points at the commits that wrote the content, which is what we were after.

blame accepts a starting point other than HEAD:

From that comes the most useful technique in the whole section: jumping over a commit to see what was there before.

When blame tells you that line 45 was touched by 3f1a8d6 and that commit turns out to be a reformatting, you want to know who touched it before. The answer is to blame that commit's parent:

3f1a8d6^ is "the parent of 3f1a8d6" (lesson 02-06). By blaming the file at that point, commit 3f1a8d6 ceases to exist as far as the analysis is concerned and the previous one shows up. Repeating the process you can go back layer by layer:

It is tedious by hand, and that is why git log -L exists (section 6), which does that walk in one go. But the technique is worth knowing, because it always works and works on any version of Git.

Other ways of narrowing the time range:

With --since, lines whose last change predates the limit appear marked with ^ as boundary lines: "this was already here before the period you care about". It is useful for answering "what has been touched in this file this quarter?" without three-year-old noise.

blame gives a snapshot: the current state and who touched each line last. git log -L gives the film: every commit that has affected a range of lines, with its diff.

Mystery solved in a single command. The two replace calls are not arbitrary: they protect against the invisible characters that arrive when pasting text from email. Deleting that function would have reintroduced a real and hard-to-reproduce fault.

The forms of -L are the same as in blame:

Very useful combinations:

The comparison between the two tools, which is the one to be clear about:

The natural flow is to chain them: blame to locate the area and the commit, log -L to understand the evolution, and git show <sha> to read the complete commit with its message.

This section solves the problem that poisons blame most in real projects.

The task-manager team decides to adopt Prettier. Ana runs it over the whole project and commits:

A single commit, no behaviour change… and from now on git blame app.js attributes almost every line of the file to Ana. All the historical information has been buried under a cosmetic commit.

-w helps if the change was only whitespace, but Prettier also reorders, breaks long lines and changes quotes: -w is not enough.

Git analyses the file as if that commit did not exist as far as attribution is concerned. The lines it changed are attributed to the previous commit that genuinely touched them. If a line cannot be reassigned cleanly, Git marks it with an asterisk * to warn that the attribution is approximate.

Repeating --ignore-rev by hand does not scale. The solution is a version-controlled file with the list of commits to ignore:

Two formatting rules that have to be respected:

• Full 40-character hashes. Abbreviated ones will not do; Git rejects them with an error.
• Comments with #. Document what each commit was: in a year's time nobody will remember.

To get the full hash:

Now it is enabled in the configuration (lesson 01-05):

And from that moment on, every git blame in the repository applies it by itself:

The real history is back. And since the file is version-controlled, the whole team benefits as soon as they run that git config once — the same "version-controlled file + one local git config" pattern we saw with core.hooksPath in lesson 06-01.

Other related options:

How to do it right from the start: when you are about to apply a mass reformatting, do it in its own isolated commit that touches nothing else, and add it to .git-blame-ignore-revs in the following commit. A reformatting mixed in with functional changes is impossible to ignore cleanly and contaminates the history for ever. That discipline is part of what we shall see in lesson 08-02.

A practical note: the hosting platforms (GitHub, GitLab) also read .git-blame-ignore-revs and apply it in their blame view, so the file serves both locally and on the web.

Recapping Carla's complete investigation, which is the standard procedure faced with any "what is this here for?":

Four commands, two minutes, and a definitive answer: the function is not to be touched, and now Carla also knows that it ought to carry an explanatory comment. She adds it:

Note the detail: the comment references the commit. It is the way to connect the code with the full explanation without repeating it, and it saves the next person this whole investigation.

The command's name is an unfortunate historical accident. "To blame" means to hold responsible for something bad, and that has created an unpleasant association: the idea that git blame is for pointing at whoever made a mess.

That is not what it is for. Git even has an alias with a better name, inherited from other systems:

And "to annotate" describes much better what it does: enriching each line with its provenance.

The legitimate uses, all of them constructive:

• Understanding the why. This lesson's case. The commit message contains the context the code cannot express.
• Finding out who to ask. Not to reproach, but because whoever wrote something three months ago has context you do not have.
• Dating a change. "Is this line before or after the migration?"
• Assessing the risk of touching something. Three-year-old code nobody has touched and nobody remembers: proceed with care.
• Documenting backwards. As Carla has just done.

And this leads to the lesson's underlying conclusion, which is worth stating without hedging:

git blame is worth exactly what your commit messages are worth.

If the commit that comes up says "Remove invisible characters when normalising task text" with three lines explaining why, blame has solved your problem. If it says "fix", "changes" or "asdf", blame has told you who and when, but not why, which was the only thing you needed.

That is the direct connection with lesson 08-01: Writing Good Commit Messages. There we shall see how to write a message that explains the intent and not the mechanics. And the definitive argument for doing it properly is this: you do not write the message for today, you write it for the git blame somebody will run two years from now — and that somebody will probably be you.

In the same way, atomic commits (lesson 08-02) make blame point at a comprehensible change rather than at a 900-line commit entitled "Friday's work".

Mistake 1: believing blame says who wrote the line. It says who touched it last. Without -w, -M, -C and --ignore-rev, the answer is usually "the last person to run the formatter".

Mistake 2: blaming the whole file. Hundreds of lines of output to investigate five. Always use -L, and above all -L :function:file.

Mistake 3: stopping at the first commit that shows up. If it is a move or a reformatting, keep pulling the thread with git blame <sha>^ -- <file> or go straight to git log -L.

Mistake 4: using blame to look for a line that no longer exists. blame only sees the current state. For deleted code, git log -L, git log -S "text" (pickaxe) or git log -p -- <file>.

Mistake 5: abbreviated hashes in .git-blame-ignore-revs. Git demands all 40 characters and fails with an unclear error if you leave them out. Get them with git rev-parse.

Mistake 6: mixing reformatting and functional changes in one commit. That commit can no longer be ignored cleanly and it contaminates the file's blame for ever. Reformatting always goes in its own commit.

Mistake 7: using blame to apportion responsibility. As well as being toxic, it is technically unreliable: the attribution depends on the options you use.

Tip 1: create an alias. You will see them in lesson 06-04, but bring it forward now:

Tip 2: chain the three tools. blame to locate, log -L for the evolution, show for the complete commit. It is the standard procedure and it does not fail.

Tip 3: when you solve a mystery, document it in the code. A comment with the reference to the commit saves the next people the investigation.

Tip 4: blame in the editor. Practically every modern editor has an integration (GitLens in VS Code, :Git blame in Vim with fugitive, IntelliJ's built-in annotation). They show the commit for the line under the cursor without leaving the file. Configure them with -w if they let you.

Tip 5: combine it with bisect. When bisect (lesson 06-02) gives you the guilty commit, blame on the lines it changed tells you what was there before and why it was like that.

Create a repository with an app.js file that evolves over five commits from three different authors (you can change author with git commit --author="Name <email>"). Then:

1. Run git blame app.js and check that each line is attributed to the right commit.
2. Narrow down with -L to a range of three lines.
3. Use -L :functionName:app.js to narrow down to a function.
4. Try -s, -e and --date=short and compare the outputs.

On the previous repository:

1. Make a commit that reindents the whole file (from 2 to 4 spaces) without changing anything else.
2. Run git blame and check that every line now belongs to that commit.
3. Check that -w recovers the original attribution.
4. Make another commit that changes double quotes to single ones throughout the file, and check that -w is no longer enough.
5. Create a .git-blame-ignore-revs with that commit, configure blame.ignoreRevsFile and check that the attribution comes back.

On the same repository:

1. Use git log -L :functionName:app.js and describe the function's evolution.
2. Add a line to the function, commit it, and delete it in another commit.
3. Check that git blame shows no trace of that line, but git log -L does.
4. Locate that same deleted line using the git log -S pickaxe from lesson 02-06.

Solution 1:

Note an instructive detail: line 2 is attributed to Bruno even though return text was conceptually written by Carla. That is because Bruno modified that line when splitting the expression over several lines. blame operates on lines, not on intentions.

Solution 2:

The change is not a whitespace one, so -w does not see through it.

The real attribution is back, and now it is automatic for the whole repository.

Solution 3:

Four commits: two cosmetic and two of real content. The complete film, including what blame with --ignore-revs deliberately hides.

-S counts occurrences of the string and shows the commits where that number changes: the one that introduced it and the one that removed it. It is the tool for what is no longer there.

git blame turns the history into a line-by-line annotation of the code in front of you. The essentials:

• It answers "which commit touched this line last?", on the file's current state. It does not say who wrote it originally, and it does not see deleted lines.
• The output has five columns — hash, author, date, line number and content; ^ marks the boundary commit and 00000000 the uncommitted changes.
• -L narrows down, and -L :function:file is the most convenient way of doing it without counting lines.
• -w, -M and -C are what separates a useful attribution from a useless one: they ignore whitespace and follow moved or copied code, within and between files, at increasing levels (-C, -C -C, -C -C -C).
• git blame <sha>^ -- <file> jumps over a commit to see what was there before: the manual technique for pulling the thread.
• git log -L gives the complete film where blame gives the snapshot: every commit that affected a range, with its diffs, including deleted lines.
• --ignore-rev and .git-blame-ignore-revs (with blame.ignoreRevsFile) neutralise mass reformattings and give the real history back. For it to work, the reformatting has to be in its own isolated commit.
• The standard procedure faced with any "what is this here for?": blame → log -L → show, and grep/log -S to see who else depends on it.
• And most importantly: it is attribution, not fault, and it is worth whatever your commit messages are worth (lesson 08-01).

Carla and the team now have a considerable querying arsenal: log with its filters and its pickaxe, bisect, blame, log -L, show. The problem is that the useful invocations are getting longer and longer — git blame -w -C --date=short -L :function:app.js app.js is not something you type by hand twice — and that there are views of the history we still do not know how to ask for: the complete branch graph, merges only, who has contributed how much, or a one-line format with colours that reads at a glance.

It is time to level up with git log and, above all, to stop typing all this by hand. That is lesson 06-04: Git Log and Aliases.