1git-blame(1) 2============ 3 4NAME 5---- 6git-blame - Show what revision and author last modified each line of a file 7 8SYNOPSIS 9-------- 10[verse] 11'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>] 12 [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file> 13 14DESCRIPTION 15----------- 16 17Annotates each line in the given file with information from the revision which 18last modified the line. Optionally, start annotating from the given revision. 19 20Also it can limit the range of lines annotated. 21 22This report doesn't tell you anything about lines which have been deleted or 23replaced; you need to use a tool such as gitlink:git-diff[1] or the "pickaxe" 24interface briefly mentioned in the following paragraph. 25 26Apart from supporting file annotation, git also supports searching the 27development history for when a code snippet occurred in a change. This makes it 28possible to track when a code snippet was added to a file, moved or copied 29between files, and eventually deleted or replaced. It works by searching for 30a text string in the diff. A small example: 31 32----------------------------------------------------------------------------- 33$ git log --pretty=oneline -S'blame_usage' 345040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file> 35ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output 36----------------------------------------------------------------------------- 37 38OPTIONS 39------- 40-c, --compatibility:: 41 Use the same output mode as gitlink:git-annotate[1] (Default: off). 42 43-L n,m:: 44 Annotate only the specified line range (lines count from 1). 45 46-l, --long:: 47 Show long rev (Default: off). 48 49-t, --time:: 50 Show raw timestamp (Default: off). 51 52-S, --rev-file <revs-file>:: 53 Use revs from revs-file instead of calling gitlink:git-rev-list[1]. 54 55-f, --show-name:: 56 Show filename in the original commit. By default 57 filename is shown if there is any line that came from a 58 file with different name, due to rename detection. 59 60-n, --show-number:: 61 Show line number in the original commit (Default: off). 62 63-p, --porcelain:: 64 Show in a format designed for machine consumption. 65 66--incremental:: 67 Show the result incrementally in a format designed for 68 machine consumption. 69 70--contents <file>:: 71 When <rev> is not specified, the command annotates the 72 changes starting backwards from the working tree copy. 73 This flag makes the command pretend as if the working 74 tree copy has the contents of he named file (specify 75 `-` to make the command read from the standard input). 76 77-M:: 78 Detect moving lines in the file as well. When a commit 79 moves a block of lines in a file (e.g. the original file 80 has A and then B, and the commit changes it to B and 81 then A), traditional 'blame' algorithm typically blames 82 the lines that were moved up (i.e. B) to the parent and 83 assigns blame to the lines that were moved down (i.e. A) 84 to the child commit. With this option, both groups of 85 lines are blamed on the parent. 86 87-C:: 88 In addition to `-M`, detect lines copied from other 89 files that were modified in the same commit. This is 90 useful when you reorganize your program and move code 91 around across files. When this option is given twice, 92 the command looks for copies from all other files in the 93 parent for the commit that creates the file in addition. 94 95-h, --help:: 96 Show help message. 97 98 99THE PORCELAIN FORMAT 100-------------------- 101 102In this format, each line is output after a header; the 103header at the minimum has the first line which has: 104 105- 40-byte SHA-1 of the commit the line is attributed to; 106- the line number of the line in the original file; 107- the line number of the line in the final file; 108- on a line that starts a group of line from a different 109 commit than the previous one, the number of lines in this 110 group. On subsequent lines this field is absent. 111 112This header line is followed by the following information 113at least once for each commit: 114 115- author name ("author"), email ("author-mail"), time 116 ("author-time"), and timezone ("author-tz"); similarly 117 for committer. 118- filename in the commit the line is attributed to. 119- the first line of the commit log message ("summary"). 120 121The contents of the actual line is output after the above 122header, prefixed by a TAB. This is to allow adding more 123header elements later. 124 125 126SPECIFYING RANGES 127----------------- 128 129Unlike `git-blame` and `git-annotate` in older git, the extent 130of annotation can be limited to both line ranges and revision 131ranges. When you are interested in finding the origin for 132ll. 40-60 for file `foo`, you can use `-L` option like these 133(they mean the same thing -- both ask for 21 lines starting at 134line 40): 135 136 git blame -L 40,60 foo 137 git blame -L 40,+21 foo 138 139Also you can use regular expression to specify the line range. 140 141 git blame -L '/^sub hello {/,/^}$/' foo 142 143would limit the annotation to the body of `hello` subroutine. 144 145When you are not interested in changes older than the version 146v2.6.18, or changes older than 3 weeks, you can use revision 147range specifiers similar to `git-rev-list`: 148 149 git blame v2.6.18.. -- foo 150 git blame --since=3.weeks -- foo 151 152When revision range specifiers are used to limit the annotation, 153lines that have not changed since the range boundary (either the 154commit v2.6.18 or the most recent commit that is more than 3 155weeks old in the above example) are blamed for that range 156boundary commit. 157 158A particularly useful way is to see if an added file have lines 159created by copy-and-paste from existing files. Sometimes this 160indicates that the developer was being sloppy and did not 161refactor the code properly. You can first find the commit that 162introduced the file with: 163 164 git log --diff-filter=A --pretty=short -- foo 165 166and then annotate the change between the commit and its 167parents, using `commit{caret}!` notation: 168 169 git blame -C -C -f $commit^! -- foo 170 171 172INCREMENTAL OUTPUT 173------------------ 174 175When called with `--incremental` option, the command outputs the 176result as it is built. The output generally will talk about 177lines touched by more recent commits first (i.e. the lines will 178be annotated out of order) and is meant to be used by 179interactive viewers. 180 181The output format is similar to the Porcelain format, but it 182does not contain the actual lines from the file that is being 183annotated. 184 185. Each blame entry always starts with a line of: 186 187 <40-byte hex sha1> <sourceline> <resultline> <num_lines> 188+ 189Line numbers count from 1. 190 191. The first time that commit shows up in the stream, it has various 192 other information about it printed out with a one-word tag at the 193 beginning of each line about that "extended commit info" (author, 194 email, committer, dates, summary etc). 195 196. Unlike Porcelain format, the filename information is always 197 given and terminates the entry: 198 199 "filename" <whitespace-quoted-filename-goes-here> 200+ 201and thus it's really quite easy to parse for some line- and word-oriented 202parser (which should be quite natural for most scripting languages). 203+ 204[NOTE] 205For people who do parsing: to make it more robust, just ignore any 206lines in between the first and last one ("<sha1>" and "filename" lines) 207where you don't recognize the tag-words (or care about that particular 208one) at the beginning of the "extended information" lines. That way, if 209there is ever added information (like the commit encoding or extended 210commit commentary), a blame viewer won't ever care. 211 212 213SEE ALSO 214-------- 215gitlink:git-annotate[1] 216 217AUTHOR 218------ 219Written by Junio C Hamano <junkio@cox.net> 220 221GIT 222--- 223Part of the gitlink:git[7] suite