1GIT-BLAME(1) Git Manual GIT-BLAME(1)
2
6 git-blame - Show what revision and author last modified each line of a
7 file
8
10 git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
11 [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
12 [--ignore-rev <rev>] [--ignore-revs-file <file>]
13 [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>]
14 [--] <file>
15
17 Annotates each line in the given file with information from the
18 revision which last modified the line. Optionally, start annotating
19 from the given revision.
20 When specified one or more times, -L restricts annotation to the
22 requested lines.
23 The origin of lines is automatically followed across whole-file renames
25 (currently there is no option to turn the rename-following off). To
26 follow lines moved from one file to another, or to follow lines that
27 were copied and pasted from another file, etc., see the -C and -M
28 options.
29 The report does not tell you anything about lines which have been
31 deleted or replaced; you need to use a tool such as git diff or the
32 "pickaxe" interface briefly mentioned in the following paragraph.
33 Apart from supporting file annotation, Git also supports searching the
35 development history for when a code snippet occurred in a change. This
36 makes it possible to track when a code snippet was added to a file,
37 moved or copied between files, and eventually deleted or replaced. It
38 works by searching for a text string in the diff. A small example of
39 the pickaxe interface that searches for blame_usage:
40 $ git log --pretty=oneline -S'blame_usage'
42 5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
43 ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
44
46 -b
47 Show blank SHA-1 for boundary commits. This can also be controlled
48 via the blame.blankboundary config option.
49 --root
51 Do not treat root commits as boundaries. This can also be
52 controlled via the blame.showRoot config option.
53 --show-stats
55 Include additional statistics at the end of blame output.
56 -L <start>,<end>, -L :<funcname>
58 Annotate only the given line range. May be specified multiple
59 times. Overlapping ranges are allowed.
60 <start> and <end> are optional. “-L <start>” or “-L <start>,”
62 spans from <start> to end of file. “-L ,<end>” spans from start of
63 file to <end>.
64 <start> and <end> can take one of these forms:
66 · number
68 If <start> or <end> is a number, it specifies an absolute line
70 number (lines count from 1).
71 · /regex/
73 This form will use the first line matching the given POSIX
75 regex. If <start> is a regex, it will search from the end of
76 the previous -L range, if any, otherwise from the start of
77 file. If <start> is “^/regex/”, it will search from the start
78 of file. If <end> is a regex, it will search starting at the
79 line given by <start>.
80 · +offset or -offset
82 This is only valid for <end> and will specify a number of lines
84 before or after the line given by <start>.
85 If “:<funcname>” is given in place of <start> and <end>, it is a
87 regular expression that denotes the range from the first funcname
88 line that matches <funcname>, up to the next funcname line.
89 “:<funcname>” searches from the end of the previous -L range, if
90 any, otherwise from the start of file. “^:<funcname>” searches
91 from the start of file.
92 -l
94 Show long rev (Default: off).
95 -t
97 Show raw timestamp (Default: off).
98 -S <revs-file>
100 Use revisions from revs-file instead of calling git-rev-list(1).
101 --reverse <rev>..<rev>
103 Walk history forward instead of backward. Instead of showing the
104 revision in which a line appeared, this shows the last revision in
105 which a line has existed. This requires a range of revision like
106 START..END where the path to blame exists in START. git blame
107 --reverse START is taken as git blame --reverse START..HEAD for
108 convenience.
109 -p, --porcelain
111 Show in a format designed for machine consumption.
112 --line-porcelain
114 Show the porcelain format, but output commit information for each
115 line, not just the first time a commit is referenced. Implies
116 --porcelain.
117 --incremental
119 Show the result incrementally in a format designed for machine
120 consumption.
121 --encoding=<encoding>
123 Specifies the encoding used to output author names and commit
124 summaries. Setting it to none makes blame output unconverted data.
125 For more information see the discussion about encoding in the git-
126 log(1) manual page.
127 --contents <file>
129 When <rev> is not specified, the command annotates the changes
130 starting backwards from the working tree copy. This flag makes the
131 command pretend as if the working tree copy has the contents of the
132 named file (specify - to make the command read from the standard
133 input).
134 --date <format>
136 Specifies the format used to output dates. If --date is not
137 provided, the value of the blame.date config variable is used. If
138 the blame.date config variable is also not set, the iso format is
139 used. For supported values, see the discussion of the --date option
140 at git-log(1).
141 --[no-]progress
143 Progress status is reported on the standard error stream by default
144 when it is attached to a terminal. This flag enables progress
145 reporting even if not attached to a terminal. Can’t use --progress
146 together with --porcelain or --incremental.
147 -M[<num>]
149 Detect moved or copied lines within a file. When a commit moves or
150 copies a block of lines (e.g. the original file has A and then B,
151 and the commit changes it to B and then A), the traditional blame
152 algorithm notices only half of the movement and typically blames
153 the lines that were moved up (i.e. B) to the parent and assigns
154 blame to the lines that were moved down (i.e. A) to the child
155 commit. With this option, both groups of lines are blamed on the
156 parent by running extra passes of inspection.
157 <num> is optional but it is the lower bound on the number of
159 alphanumeric characters that Git must detect as moving/copying
160 within a file for it to associate those lines with the parent
161 commit. The default value is 20.
162 -C[<num>]
164 In addition to -M, detect lines moved or copied from other files
165 that were modified in the same commit. This is useful when you
166 reorganize your program and move code around across files. When
167 this option is given twice, the command additionally looks for
168 copies from other files in the commit that creates the file. When
169 this option is given three times, the command additionally looks
170 for copies from other files in any commit.
171 <num> is optional but it is the lower bound on the number of
173 alphanumeric characters that Git must detect as moving/copying
174 between files for it to associate those lines with the parent
175 commit. And the default value is 40. If there are more than one -C
176 options given, the <num> argument of the last -C will take effect.
177 --ignore-rev <rev>
179 Ignore changes made by the revision when assigning blame, as if the
180 change never happened. Lines that were changed or added by an
181 ignored commit will be blamed on the previous commit that changed
182 that line or nearby lines. This option may be specified multiple
183 times to ignore more than one revision. If the
184 blame.markIgnoredLines config option is set, then lines that were
185 changed by an ignored commit and attributed to another commit will
186 be marked with a ? in the blame output. If the
187 blame.markUnblamableLines config option is set, then those lines
188 touched by an ignored commit that we could not attribute to another
189 revision are marked with a *.
190 --ignore-revs-file <file>
192 Ignore revisions listed in file, which must be in the same format
193 as an fsck.skipList. This option may be repeated, and these files
194 will be processed after any files specified with the
195 blame.ignoreRevsFile config option. An empty file name, "", will
196 clear the list of revs from previously processed files.
197 -h
199 Show help message.
200 -c
202 Use the same output mode as git-annotate(1) (Default: off).
203 --score-debug
205 Include debugging information related to the movement of lines
206 between files (see -C) and lines moved within a file (see -M). The
207 first number listed is the score. This is the number of
208 alphanumeric characters detected as having been moved between or
209 within files. This must be above a certain threshold for git blame
210 to consider those lines of code to have been moved.
211 -f, --show-name
213 Show the filename in the original commit. By default the filename
214 is shown if there is any line that came from a file with a
215 different name, due to rename detection.
216 -n, --show-number
218 Show the line number in the original commit (Default: off).
219 -s
221 Suppress the author name and timestamp from the output.
222 -e, --show-email
224 Show the author email instead of author name (Default: off). This
225 can also be controlled via the blame.showEmail config option.
226 -w
228 Ignore whitespace when comparing the parent’s version and the
229 child’s to find where the lines came from.
230 --abbrev=<n>
232 Instead of using the default 7+1 hexadecimal digits as the
233 abbreviated object name, use <n>+1 digits. Note that 1 column is
234 used for a caret to mark the boundary commit.
235
237 In this format, each line is output after a header; the header at the
238 minimum has the first line which has:
239 · 40-byte SHA-1 of the commit the line is attributed to;
241 · the line number of the line in the original file;
243 · the line number of the line in the final file;
245 · on a line that starts a group of lines from a different commit than
247 the previous one, the number of lines in this group. On subsequent
248 lines this field is absent.
249 This header line is followed by the following information at least once
251 for each commit:
252 · the author name ("author"), email ("author-mail"), time
254 ("author-time"), and time zone ("author-tz"); similarly for
255 committer.
256 · the filename in the commit that the line is attributed to.
258 · the first line of the commit log message ("summary").
260 The contents of the actual line is output after the above header,
262 prefixed by a TAB. This is to allow adding more header elements later.
263 The porcelain format generally suppresses commit information that has
265 already been seen. For example, two lines that are blamed to the same
266 commit will both be shown, but the details for that commit will be
267 shown only once. This is more efficient, but may require more state be
268 kept by the reader. The --line-porcelain option can be used to output
269 full commit information for each line, allowing simpler (but less
270 efficient) usage like:
271 # count the number of lines attributed to each author
273 git blame --line-porcelain file |
274 sed -n 's/^author //p' |
275 sort | uniq -c | sort -rn
276
278 Unlike git blame and git annotate in older versions of git, the extent
279 of the annotation can be limited to both line ranges and revision
280 ranges. The -L option, which limits annotation to a range of lines, may
281 be specified multiple times.
282 When you are interested in finding the origin for lines 40-60 for file
284 foo, you can use the -L option like so (they mean the same thing — both
285 ask for 21 lines starting at line 40):
286 git blame -L 40,60 foo
288 git blame -L 40,+21 foo
289 Also you can use a regular expression to specify the line range:
291 git blame -L '/^sub hello {/,/^}$/' foo
293 which limits the annotation to the body of the hello subroutine.
295 When you are not interested in changes older than version v2.6.18, or
297 changes older than 3 weeks, you can use revision range specifiers
298 similar to git rev-list:
299 git blame v2.6.18.. -- foo
301 git blame --since=3.weeks -- foo
302 When revision range specifiers are used to limit the annotation, lines
304 that have not changed since the range boundary (either the commit
305 v2.6.18 or the most recent commit that is more than 3 weeks old in the
306 above example) are blamed for that range boundary commit.
307 A particularly useful way is to see if an added file has lines created
309 by copy-and-paste from existing files. Sometimes this indicates that
310 the developer was being sloppy and did not refactor the code properly.
311 You can first find the commit that introduced the file with:
312 git log --diff-filter=A --pretty=short -- foo
314 and then annotate the change between the commit and its parents, using
316 commit^! notation:
317 git blame -C -C -f $commit^! -- foo
319
321 When called with --incremental option, the command outputs the result
322 as it is built. The output generally will talk about lines touched by
323 more recent commits first (i.e. the lines will be annotated out of
324 order) and is meant to be used by interactive viewers.
325 The output format is similar to the Porcelain format, but it does not
327 contain the actual lines from the file that is being annotated.
328 1. Each blame entry always starts with a line of:
330 <40-byte hex sha1> <sourceline> <resultline> <num_lines>
332 Line numbers count from 1.
334 2. The first time that a commit shows up in the stream, it has various
336 other information about it printed out with a one-word tag at the
337 beginning of each line describing the extra commit information
338 (author, email, committer, dates, summary, etc.).
339 3. Unlike the Porcelain format, the filename information is always
341 given and terminates the entry:
342 "filename" <whitespace-quoted-filename-goes-here>
344 and thus it is really quite easy to parse for some line- and
346 word-oriented parser (which should be quite natural for most
347 scripting languages).
348 Note
350 For people who do parsing: to make it more robust, just ignore
351 any lines between the first and last one ("<sha1>" and
352 "filename" lines) where you do not recognize the tag words (or
353 care about that particular one) at the beginning of the
354 "extended information" lines. That way, if there is ever added
355 information (like the commit encoding or extended commit
356 commentary), a blame viewer will not care.
357
359 If the file .mailmap exists at the toplevel of the repository, or at
360 the location pointed to by the mailmap.file or mailmap.blob
361 configuration options, it is used to map author and committer names and
362 email addresses to canonical real names and email addresses.
363 In the simple form, each line in the file consists of the canonical
365 real name of an author, whitespace, and an email address used in the
366 commit (enclosed by < and >) to map to the name. For example:
367 Proper Name <commit@email.xx>
369 The more complex forms are:
371 <proper@email.xx> <commit@email.xx>
373 which allows mailmap to replace only the email part of a commit, and:
375 Proper Name <proper@email.xx> <commit@email.xx>
377 which allows mailmap to replace both the name and the email of a commit
379 matching the specified commit email address, and:
380 Proper Name <proper@email.xx> Commit Name <commit@email.xx>
382 which allows mailmap to replace both the name and the email of a commit
384 matching both the specified commit name and email address.
385 Example 1: Your history contains commits by two authors, Jane and Joe,
387 whose names appear in the repository under several forms:
388 Joe Developer <joe@example.com>
390 Joe R. Developer <joe@example.com>
391 Jane Doe <jane@example.com>
392 Jane Doe <jane@laptop.(none)>
393 Jane D. <jane@desktop.(none)>
394 Now suppose that Joe wants his middle name initial used, and Jane
396 prefers her family name fully spelled out. A proper .mailmap file would
397 look like:
398 Jane Doe <jane@desktop.(none)>
400 Joe R. Developer <joe@example.com>
401 Note how there is no need for an entry for <jane@laptop.(none)>,
403 because the real name of that author is already correct.
404 Example 2: Your repository contains commits from the following authors:
406 nick1 <bugs@company.xx>
408 nick2 <bugs@company.xx>
409 nick2 <nick2@company.xx>
410 santa <me@company.xx>
411 claus <me@company.xx>
412 CTO <cto@coompany.xx>
413 Then you might want a .mailmap file that looks like:
415 <cto@company.xx> <cto@coompany.xx>
417 Some Dude <some@dude.xx> nick1 <bugs@company.xx>
418 Other Author <other@author.xx> nick2 <bugs@company.xx>
419 Other Author <other@author.xx> <nick2@company.xx>
420 Santa Claus <santa.claus@northpole.xx> <me@company.xx>
421 Use hash # for comments that are either on their own line, or after the
423 email address.
424
426 git-annotate(1)
427
429 Part of the git(1) suite
430Git 2.26.2 2020-04-20 GIT-BLAME(1)