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