Document 'git-blame --incremental'

Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
Junio C Hamano 2007-01-28 12:21:53 -08:00
Родитель 4f193f20a3
Коммит 57e7a0a494
1 изменённых файлов: 46 добавлений и 1 удалений

Просмотреть файл

@ -8,7 +8,7 @@ git-blame - Show what revision and author last modified each line of a file
SYNOPSIS
--------
[verse]
'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>]
'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>]
[-M] [-C] [-C] [--since=<date>] [<rev>] [--] <file>
DESCRIPTION
@ -63,6 +63,10 @@ OPTIONS
-p, --porcelain::
Show in a format designed for machine consumption.
--incremental::
Show the result incrementally 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
@ -158,6 +162,47 @@ parents, using `commit{caret}!` notation:
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]