| 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 | [synopsis] |
| 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 | [--color-lines] [--color-by-age] [--progress] [--abbrev=<n>] |
| 15 | [ --contents <file> ] [<rev> | --reverse <rev>..<rev>] [--] <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.adoc[] |
| 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 the 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 | include::diff-algorithm-option.adoc[] |
| 89 | |
| 90 | `--abbrev=<n>`:: |
| 91 | Instead of using the default _7+1_ hexadecimal digits as the |
| 92 | abbreviated object name, use _<m>+1_ digits, where _<m>_ is at |
| 93 | least _<n>_ but ensures the commit object names are unique. |
| 94 | Note that 1 column |
| 95 | is used for a caret to mark the boundary commit. |
| 96 | |
| 97 | |
| 98 | THE DEFAULT FORMAT |
| 99 | ------------------ |
| 100 | |
| 101 | When neither `--porcelain` nor `--incremental` option is specified, |
| 102 | `git blame` will output annotation for each line with: |
| 103 | |
| 104 | - abbreviated object name for the commit the line came from; |
| 105 | - author ident (by default the author name and date, unless `-s` or `-e` |
| 106 | is specified); and |
| 107 | - line number |
| 108 | |
| 109 | before the line contents. |
| 110 | |
| 111 | THE PORCELAIN FORMAT |
| 112 | -------------------- |
| 113 | |
| 114 | In this format, each line is output after a header; the |
| 115 | header at the minimum has the first line which has: |
| 116 | |
| 117 | - 40-byte SHA-1 of the commit the line is attributed to; |
| 118 | - the line number of the line in the original file; |
| 119 | - the line number of the line in the final file; |
| 120 | - on a line that starts a group of lines from a different |
| 121 | commit than the previous one, the number of lines in this |
| 122 | group. On subsequent lines this field is absent. |
| 123 | |
| 124 | This header line is followed by the following information |
| 125 | at least once for each commit: |
| 126 | |
| 127 | - the author name (`author`), email (`author-mail`), time |
| 128 | (`author-time`), and time zone (`author-tz`); similarly |
| 129 | for committer. |
| 130 | - the filename in the commit that the line is attributed to. |
| 131 | - the first line of the commit log message (`summary`). |
| 132 | |
| 133 | The contents of the actual line are output after the above |
| 134 | header, prefixed by a _TAB_. This is to allow adding more |
| 135 | header elements later. |
| 136 | |
| 137 | The porcelain format generally suppresses commit information that has |
| 138 | already been seen. For example, two lines that are blamed to the same |
| 139 | commit will both be shown, but the details for that commit will be shown |
| 140 | only once. Information which is specific to individual lines will not be |
| 141 | grouped together, like revs to be marked `ignored` or `unblamable`. This |
| 142 | is more efficient, but may require more state be kept by the reader. The |
| 143 | `--line-porcelain` option can be used to output full commit information |
| 144 | for each line, allowing simpler (but less efficient) usage like: |
| 145 | |
| 146 | # count the number of lines attributed to each author |
| 147 | git blame --line-porcelain file | |
| 148 | sed -n 's/^author //p' | |
| 149 | sort | uniq -c | sort -rn |
| 150 | |
| 151 | |
| 152 | SPECIFYING RANGES |
| 153 | ----------------- |
| 154 | |
| 155 | Unlike `git blame` and `git annotate` in older versions of git, the extent |
| 156 | of the annotation can be limited to both line ranges and revision |
| 157 | ranges. The `-L` option, which limits annotation to a range of lines, may be |
| 158 | specified multiple times. |
| 159 | |
| 160 | When you are interested in finding the origin for |
| 161 | lines 40-60 for file `foo`, you can use the `-L` option like so |
| 162 | (they mean the same thing -- both ask for 21 lines starting at |
| 163 | line 40): |
| 164 | |
| 165 | git blame -L 40,60 foo |
| 166 | git blame -L 40,+21 foo |
| 167 | |
| 168 | Also you can use a regular expression to specify the line range: |
| 169 | |
| 170 | git blame -L '/^sub hello {/,/^}$/' foo |
| 171 | |
| 172 | which limits the annotation to the body of the `hello` subroutine. |
| 173 | |
| 174 | When you are not interested in changes older than version |
| 175 | v2.6.18, or changes older than 3 weeks, you can use revision |
| 176 | range specifiers similar to `git rev-list`: |
| 177 | |
| 178 | git blame v2.6.18.. -- foo |
| 179 | git blame --since=3.weeks -- foo |
| 180 | |
| 181 | When revision range specifiers are used to limit the annotation, |
| 182 | lines that have not changed since the range boundary (either the |
| 183 | commit v2.6.18 or the most recent commit that is more than 3 |
| 184 | weeks old in the above example) are blamed for that range |
| 185 | boundary commit. |
| 186 | |
| 187 | A particularly useful way is to see if an added file has lines |
| 188 | created by copy-and-paste from existing files. Sometimes this |
| 189 | indicates that the developer was being sloppy and did not |
| 190 | refactor the code properly. You can first find the commit that |
| 191 | introduced the file with: |
| 192 | |
| 193 | git log --diff-filter=A --pretty=short -- foo |
| 194 | |
| 195 | and then annotate the change between the commit and its |
| 196 | parents, using `commit^!` notation: |
| 197 | |
| 198 | git blame -C -C -f $commit^! -- foo |
| 199 | |
| 200 | |
| 201 | INCREMENTAL OUTPUT |
| 202 | ------------------ |
| 203 | |
| 204 | When called with `--incremental` option, the command outputs the |
| 205 | result as it is built. The output generally will talk about |
| 206 | lines touched by more recent commits first (i.e. the lines will |
| 207 | be annotated out of order) and is meant to be used by |
| 208 | interactive viewers. |
| 209 | |
| 210 | The output format is similar to the Porcelain format, but it |
| 211 | does not contain the actual lines from the file that is being |
| 212 | annotated. |
| 213 | |
| 214 | . Each blame entry always starts with a line of: |
| 215 | + |
| 216 | [synopsis] |
| 217 | <40-byte-hex-sha1> <sourceline> <resultline> <num-lines> |
| 218 | + |
| 219 | Line numbers count from 1. |
| 220 | |
| 221 | . The first time that a commit shows up in the stream, it has various |
| 222 | other information about it printed out with a one-word tag at the |
| 223 | beginning of each line describing the extra commit information (author, |
| 224 | email, committer, dates, summary, etc.). |
| 225 | |
| 226 | . Unlike the Porcelain format, the filename information is always |
| 227 | given and terminates the entry: |
| 228 | + |
| 229 | [synopsis] |
| 230 | filename <whitespace-quoted-filename-goes-here> |
| 231 | + |
| 232 | and thus it is really quite easy to parse for some line- and word-oriented |
| 233 | parser (which should be quite natural for most scripting languages). |
| 234 | + |
| 235 | [NOTE] |
| 236 | For people who do parsing: to make it more robust, just ignore any |
| 237 | lines between the first and last one (_<40-byte-hex-sha1>_ and `filename` |
| 238 | lines) where you do not recognize the tag words (or care about that particular |
| 239 | one) at the beginning of the "extended information" lines. That way, if |
| 240 | there is ever added information (like the commit encoding or extended |
| 241 | commit commentary), a blame viewer will not care. |
| 242 | |
| 243 | |
| 244 | MAPPING AUTHORS |
| 245 | --------------- |
| 246 | |
| 247 | See linkgit:gitmailmap[5]. |
| 248 | |
| 249 | CONFIGURATION |
| 250 | ------------- |
| 251 | |
| 252 | include::includes/cmd-config-section-all.adoc[] |
| 253 | |
| 254 | include::config/blame.adoc[] |
| 255 | |
| 256 | SEE ALSO |
| 257 | -------- |
| 258 | linkgit:git-annotate[1] |
| 259 | |
| 260 | GIT |
| 261 | --- |
| 262 | Part of the linkgit:git[1] suite |