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