]>
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 JH |
10 | [verse] |
11 | 'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] | |
12 | [-M] [-C] [-C] [--since=<date>] [<rev>] [--] <file> | |
8f2b72a9 JF |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
26e8c5d3 JF |
16 | |
17 | Annotates each line in the given file with information from the revision which | |
18 | last modified the line. Optionally, start annotating from the given revision. | |
19 | ||
acca687f JH |
20 | Also it can limit the range of lines annotated. |
21 | ||
26e8c5d3 JF |
22 | This report doesn't tell you anything about lines which have been deleted or |
23 | replaced; you need to use a tool such as gitlink:git-diff[1] or the "pickaxe" | |
24 | interface briefly mentioned in the following paragraph. | |
25 | ||
26 | Apart from supporting file annotation, git also supports searching the | |
27 | development history for when a code snippet occured in a change. This makes it | |
28 | possible to track when a code snippet was added to a file, moved or copied | |
29 | between files, and eventually deleted or replaced. It works by searching for | |
30 | a text string in the diff. A small example: | |
31 | ||
32 | ----------------------------------------------------------------------------- | |
33 | $ git log --pretty=oneline -S'blame_usage' | |
34 | 5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file> | |
35 | ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output | |
36 | ----------------------------------------------------------------------------- | |
8f2b72a9 JF |
37 | |
38 | OPTIONS | |
39 | ------- | |
abda1ef5 | 40 | -c, --compatibility:: |
26e8c5d3 | 41 | Use the same output mode as gitlink:git-annotate[1] (Default: off). |
8f2b72a9 | 42 | |
acca687f JH |
43 | -L n,m:: |
44 | Annotate only the specified line range (lines count from | |
45 | 1). The range can be specified with a regexp. For | |
46 | example, `-L '/^sub esc_html /,/^}$/'` limits the | |
47 | annotation only to the body of `esc_html` subroutine. | |
48 | ||
8f2b72a9 | 49 | -l, --long:: |
b19ee24b FK |
50 | Show long rev (Default: off). |
51 | ||
52 | -t, --time:: | |
53 | Show raw timestamp (Default: off). | |
8f2b72a9 JF |
54 | |
55 | -S, --rev-file <revs-file>:: | |
26e8c5d3 | 56 | Use revs from revs-file instead of calling gitlink:git-rev-list[1]. |
8f2b72a9 | 57 | |
b24642b2 JH |
58 | -f, --show-name:: |
59 | Show filename in the original commit. By default | |
60 | filename is shown if there is any line that came from a | |
61 | file with different name, due to rename detection. | |
62 | ||
63 | -n, --show-number:: | |
64 | Show line number in the original commit (Default: off). | |
65 | ||
66 | -p, --porcelain:: | |
67 | Show in a format designed for machine consumption. | |
68 | ||
acca687f JH |
69 | -M:: |
70 | Detect moving lines in the file as well. When a commit | |
71 | moves a block of lines in a file (e.g. the original file | |
72 | has A and then B, and the commit changes it to B and | |
73 | then A), traditional 'blame' algorithm typically blames | |
74 | the lines that were moved up (i.e. B) to the parent and | |
75 | assigns blame to the lines that were moved down (i.e. A) | |
76 | to the child commit. With this option, both groups of | |
77 | lines are blamed on the parent. | |
78 | ||
79 | -C:: | |
80 | In addition to `-M`, detect lines copied from other | |
81 | files that were modified in the same commit. This is | |
82 | useful when you reorganize your program and move code | |
83 | around across files. When this option is given twice, | |
84 | the command looks for copies from all other files in the | |
85 | parent for the commit that creates the file in addition. | |
86 | ||
8f2b72a9 JF |
87 | -h, --help:: |
88 | Show help message. | |
89 | ||
90 | ||
b24642b2 JH |
91 | THE PORCELAIN FORMAT |
92 | -------------------- | |
93 | ||
94 | In this format, each line is output after a header; the | |
95 | header at the minumum has the first line which has: | |
96 | ||
97 | - 40-byte SHA-1 of the commit the line is attributed to; | |
98 | - the line number of the line in the original file; | |
99 | - the line number of the line in the final file; | |
100 | - on a line that starts a group of line from a different | |
101 | commit than the previous one, the number of lines in this | |
102 | group. On subsequent lines this field is absent. | |
103 | ||
104 | This header line is followed by the following information | |
105 | at least once for each commit: | |
106 | ||
107 | - author name ("author"), email ("author-mail"), time | |
108 | ("author-time"), and timezone ("author-tz"); similarly | |
109 | for committer. | |
110 | - filename in the commit the line is attributed to. | |
111 | - the first line of the commit log message ("summary"). | |
112 | ||
113 | The contents of the actual line is output after the above | |
114 | header, prefixed by a TAB. This is to allow adding more | |
115 | header elements later. | |
116 | ||
acca687f JH |
117 | |
118 | SPECIFIYING RANGES | |
119 | ------------------ | |
120 | ||
121 | Unlike `git-blame` and `git-annotate` in older git, the extent | |
122 | of annotation can be limited to both line ranges and revision | |
123 | ranges. When you are interested in finding the origin for | |
124 | ll. 40-60 for file `foo`, you can use `-L` option like this: | |
125 | ||
126 | git blame -L 40,60 foo | |
127 | ||
128 | When you are not interested in changes older than the version | |
129 | v2.6.18, or changes older than 3 weeks, you can use revision | |
130 | range specifiers similar to `git-rev-list`: | |
131 | ||
132 | git blame v2.6.18.. -- foo | |
133 | git blame --since=3.weeks -- foo | |
134 | ||
135 | When revision range specifiers are used to limit the annotation, | |
136 | lines that have not changed since the range boundary (either the | |
137 | commit v2.6.18 or the most recent commit that is more than 3 | |
138 | weeks old in the above example) are blamed for that range | |
139 | boundary commit. | |
140 | ||
141 | A particularly useful way is to see if an added file have lines | |
142 | created by copy-and-paste from existing files. Sometimes this | |
143 | indicates that the developer was being sloppy and did not | |
144 | refactor the code properly. You can first find the commit that | |
145 | introduced the file with: | |
146 | ||
147 | git log --diff-filter=A --pretty=short -- foo | |
148 | ||
149 | and then annotate the change between the commit and its | |
150 | parents, using `commit{caret}!` notation: | |
151 | ||
152 | git blame -C -C -f $commit^! -- foo | |
153 | ||
154 | ||
8f2b72a9 JF |
155 | SEE ALSO |
156 | -------- | |
157 | gitlink:git-annotate[1] | |
158 | ||
159 | AUTHOR | |
160 | ------ | |
acca687f | 161 | Written by Junio C Hamano <junkio@cox.net> |
8f2b72a9 JF |
162 | |
163 | GIT | |
164 | --- | |
165 | Part of the gitlink:git[7] suite |