git-blame(1)

NAME#

git-blame - Show what revision and author last modified each line of a file

SYNOPSIS#

git blame\n [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
\n
            [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
\n
            [--ignore-rev <rev>] [--ignore-revs-file <file>]
\n
            [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>]
\n
            [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <file>

DESCRIPTION#

Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision.

When specified one or more times, -L restricts annotation to the requested lines.

The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following off). To follow lines moved from one file to another, or to follow lines that were copied and pasted from another file, etc., see the -C and -M options.

The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as git diff or the "pickaxe" interface briefly mentioned in the following paragraph.

Apart from supporting file annotation, Git also supports searching the development history for when a code snippet occurred in a change. This makes it possible to track when a code snippet was added to a file, moved or copied between files, and eventually deleted or replaced. It works by searching for a text string in the diff. A small example of the pickaxe interface that searches for blame_usage:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

OPTIONS#

-b

--root

--show-stats

-L <start>,<end>, -L :<funcname>

<start> and <end> are optional. -L <start> or -L <start>, spans from <start> to end of file. -L ,<end> spans from start of file to <end>.

<start> and <end> can take one of these forms:

If <start> or <end> is a number, it specifies an absolute line number (lines count from 1).

This form will use the first line matching the given POSIX regex. If <start> is a regex, it will search from the end of the previous -L range, if any, otherwise from the start of file. If <start> is ^/regex/, it will search from the start of file. If <end> is a regex, it will search starting at the line given by <start>.

This is only valid for <end> and will specify a number of lines before or after the line given by <start>.

If :<funcname> is given in place of <start> and <end>, it is a regular expression that denotes the range from the first funcname line that matches <funcname>, up to the next funcname line. :<funcname> searches from the end of the previous -L range, if any, otherwise from the start of file. ^:<funcname> searches from the start of file. The function names are determined in the same way as git diff works out patch hunk headers (see Defining a custom hunk-header in gitattributes(5)).

-l

-t

-S <revs-file>

--reverse <rev>..<rev>

--first-parent

-p, --porcelain

--line-porcelain

--incremental

--encoding=<encoding>

--contents <file>

--date <format>

--[no-]progress

-M[<num>]

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20.

-C[<num>]

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -C options given, the <num> argument of the last -C will take effect.

--ignore-rev <rev>

--ignore-revs-file <file>

--color-lines

--color-by-age

-h

-c

--score-debug

-f, --show-name

-n, --show-number

-s

-e, --show-email

-w

--abbrev=<n>

THE DEFAULT FORMAT#

When neither --porcelain nor --incremental option is specified, git blame will output annotation for each line with:

before the line contents.

THE PORCELAIN FORMAT#

In this format, each line is output after a header; the header at the minimum has the first line which has:

This header line is followed by the following information at least once for each commit:

The contents of the actual line are output after the above header, prefixed by a TAB. This is to allow adding more header elements later.

The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown only once. This is more efficient, but may require more state be kept by the reader. The --line-porcelain option can be used to output full commit information for each line, allowing simpler (but less efficient) usage like:

# count the number of lines attributed to each author
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

SPECIFYING RANGES#

Unlike git blame and git annotate in older versions of git, the extent of the annotation can be limited to both line ranges and revision ranges. The -L option, which limits annotation to a range of lines, may be specified multiple times.

When you are interested in finding the origin for lines 40-60 for file foo, you can use the -L option like so (they mean the same thing — both ask for 21 lines starting at line 40):

git blame -L 40,60 foo
git blame -L 40,+21 foo

Also you can use a regular expression to specify the line range:

git blame -L '/^sub hello {/,/^}$/' foo

which limits the annotation to the body of the hello subroutine.

When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision range specifiers similar to git rev-list:

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

When revision range specifiers are used to limit the annotation, lines that have not changed since the range boundary (either the commit v2.6.18 or the most recent commit that is more than 3 weeks old in the above example) are blamed for that range boundary commit.

A particularly useful way is to see if an added file has lines created by copy-and-paste from existing files. Sometimes this indicates that the developer was being sloppy and did not refactor the code properly. You can first find the commit that introduced the file with:

git log --diff-filter=A --pretty=short -- foo

and then annotate the change between the commit and its parents, using commit^! notation:

git blame -C -C -f $commit^! -- foo

INCREMENTAL OUTPUT#

When called with --incremental option, the command outputs the result as it is built. The output generally will talk about lines touched by more recent commits first (i.e. the lines will be annotated out of order) and is meant to be used by interactive viewers.

The output format is similar to the Porcelain format, but it does not contain the actual lines from the file that is being annotated.

<40-byte-hex-sha1> <sourceline> <resultline> <num-lines>

Line numbers count from 1.

"filename" <whitespace-quoted-filename-goes-here>

and thus it is really quite easy to parse for some line- and word-oriented parser (which should be quite natural for most scripting languages).

MAPPING AUTHORS#

See gitmailmap(5).

CONFIGURATION#

Everything below this line in this section is selectively included from the git-config(1) documentation. The content is the same as what’s found there:

blame.blankBoundary

blame.coloring

blame.date

blame.showEmail

blame.showRoot

blame.ignoreRevsFile

blame.markUnblamableLines

blame.markIgnoredLines

SEE ALSO#

git-annotate(1)

GIT#

Part of the git(1) suite