![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
index bdfc6669285dc895a69fc0037246810bfa979de5..8f9439a6ddfa505c0f3cd0d1f0ba826fc12cc1ba 100644 (file)
SYNOPSIS
--------
[verse]
SYNOPSIS
--------
[verse]
-'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>]
- [-M] [-C] [-C] [--since=<date>] [<rev>] [--] <file>
+'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
+ [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
+ [<rev> | --contents <file>] [--] <file>
DESCRIPTION
-----------
DESCRIPTION
-----------
interface briefly mentioned in the following paragraph.
Apart from supporting file annotation, git also supports searching the
interface briefly mentioned in the following paragraph.
Apart from supporting file annotation, git also supports searching the
-development history for when a code snippet occured in a change. This makes it
+development history for when a code snippet occurred in a change. This makes it
possible to track when a code snippet was added to a file, moved or copied
between files, and eventually deleted or replaced. It works by searching for
a text string in the diff. A small example:
possible to track when a code snippet was added to a file, moved or copied
between files, and eventually deleted or replaced. It works by searching for
a text string in the diff. A small example:
OPTIONS
-------
OPTIONS
-------
--c, --compatibility::
- Use the same output mode as gitlink:git-annotate[1] (Default: off).
-
--L n,m::
- Annotate only the specified line range (lines count from 1).
+include::blame-options.txt[]
--l, --long::
- Show long rev (Default: off).
-
--t, --time::
- Show raw timestamp (Default: off).
+-c::
+ Use the same output mode as gitlink:git-annotate[1] (Default: off).
--S, --rev-file <revs-file>::
- Use revs from revs-file instead of calling gitlink:git-rev-list[1].
+--score-debug::
+ Include debugging information related to the movement of
+ lines between files (see `-C`) and lines moved within a
+ file (see `-M`). The first number listed is the score.
+ This is the number of alphanumeric characters detected
+ to be moved between or within files. This must be above
+ a certain threshold for git-blame to consider those lines
+ of code to have been moved.
-f, --show-name::
Show filename in the original commit. By default
-f, --show-name::
Show filename in the original commit. By default
-n, --show-number::
Show line number in the original commit (Default: off).
-n, --show-number::
Show line number in the original commit (Default: off).
--p, --porcelain::
- Show in a format designed for machine consumption.
-
--M::
- Detect moving lines in the file as well. When a commit
- moves a block of lines in a file (e.g. the original file
- has A and then B, and the commit changes it to B and
- then A), traditional 'blame' algorithm typically blames
- the lines that were moved up (i.e. B) to the parent and
- assigns blame to the lines that were moved down (i.e. A)
- to the child commit. With this option, both groups of
- lines are blamed on the parent.
-
--C::
- In addition to `-M`, detect lines copied from other
- files that were modified in the same commit. This is
- useful when you reorganize your program and move code
- around across files. When this option is given twice,
- the command looks for copies from all other files in the
- parent for the commit that creates the file in addition.
-
--h, --help::
- Show help message.
-
-
THE PORCELAIN FORMAT
--------------------
In this format, each line is output after a header; the
THE PORCELAIN FORMAT
--------------------
In this format, each line is output after a header; the
-header at the minumum has the first line which has:
+header at the minimum has the first line which has:
- 40-byte SHA-1 of the commit the line is attributed to;
- the line number of the line in the original file;
- 40-byte SHA-1 of the commit the line is attributed to;
- the line number of the line in the original file;
header elements later.
header elements later.
-SPECIFIYING RANGES
-------------------
+SPECIFYING RANGES
+-----------------
Unlike `git-blame` and `git-annotate` in older git, the extent
of annotation can be limited to both line ranges and revision
ranges. When you are interested in finding the origin for
Unlike `git-blame` and `git-annotate` in older git, the extent
of annotation can be limited to both line ranges and revision
ranges. When you are interested in finding the origin for
-ll. 40-60 for file `foo`, you can use `-L` option like this:
+ll. 40-60 for file `foo`, you can use `-L` option like these
+(they mean the same thing -- both ask for 21 lines starting at
+line 40):
git blame -L 40,60 foo
git blame -L 40,60 foo
+ git blame -L 40,+21 foo
Also you can use regular expression to specify the line range.
Also you can use regular expression to specify the line range.
git blame -C -C -f $commit^! -- foo
git blame -C -C -f $commit^! -- foo
+INCREMENTAL OUTPUT
+------------------
+
+When called with `--incremental` option, the command outputs the
+result as it is built. The output generally will talk about
+lines touched by more recent commits first (i.e. the lines will
+be annotated out of order) and is meant to be used by
+interactive viewers.
+
+The output format is similar to the Porcelain format, but it
+does not contain the actual lines from the file that is being
+annotated.
+
+. Each blame entry always starts with a line of:
+
+ <40-byte hex sha1> <sourceline> <resultline> <num_lines>
++
+Line numbers count from 1.
+
+. The first time that commit shows up in the stream, it has various
+ other information about it printed out with a one-word tag at the
+ beginning of each line about that "extended commit info" (author,
+ email, committer, dates, summary etc).
+
+. Unlike Porcelain format, the filename information is always
+ given and terminates the entry:
+
+ "filename" <whitespace-quoted-filename-goes-here>
++
+and thus it's really quite easy to parse for some line- and word-oriented
+parser (which should be quite natural for most scripting languages).
++
+[NOTE]
+For people who do parsing: to make it more robust, just ignore any
+lines in between the first and last one ("<sha1>" and "filename" lines)
+where you don't recognize the tag-words (or care about that particular
+one) at the beginning of the "extended information" lines. That way, if
+there is ever added information (like the commit encoding or extended
+commit commentary), a blame viewer won't ever care.
+
+
SEE ALSO
--------
gitlink:git-annotate[1]
SEE ALSO
--------
gitlink:git-annotate[1]