Update git-annotate/git-blame documentation

Moved options that pertained to both git-blame and git-annotate to a
common file blame-options.txt.

builtin-blame.c: Removed --compatibility, --long, --time from the
short usage as they are not handled in the code.

Documentation/git-blame.txt: Removed common options to git-annotate.
Added documentation for --score-debug.  Removed --compatibility.
Adjusted usage at top to not wrap on 80 columns.

Documentation/git-annotate.txt: Using common options blame-options.txt.

Documentation/blame-options.txt: Added -b note about associated config
option, added --root note about associated config option, added
documentation for --show-stats.  Removed --long, --time, --rev-file as
those options do not really exist.  Added documentation for -M/-C taking
an optional score argument for detection of moved lines.

Signed-off-by: Andrew Ruder <andy@aeruder.net>
Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
Andrew Ruder 2007-04-16 01:20:34 -05:00 committed by Junio C Hamano
parent 0b9a9dd00a
commit 635f4a30f0
4 changed files with 85 additions and 67 deletions

View File

@ -0,0 +1,67 @@
-b::
Show blank SHA-1 for boundary commits. This can also
be controlled via the `blame.blankboundary` config option.
--root::
Do not treat root commits as boundaries. This can also be
controlled via the `blame.showroot` config option.
--show-stats::
Include additional statistics at the end of blame output.
-L n,m::
Annotate only the specified line range (lines count from 1).
-l::
Show long rev (Default: off).
-t::
Show raw timestamp (Default: off).
-S <revs-file>::
Use revs from revs-file instead of calling gitlink:git-rev-list[1].
-p, --porcelain::
Show in a format designed for machine consumption.
--incremental::
Show the result incrementally in a format designed for
machine consumption.
--contents <file>::
When <rev> is not specified, the command annotates the
changes starting backwards from the working tree copy.
This flag makes the command pretend as if the working
tree copy has the contents of he named file (specify
`-` to make the command read from the standard input).
-M|<num>|::
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.
<num> is optional but it is the lower bound on the number of
alphanumeric characters that git must detect as moving
within a file for it to associate those lines with the parent
commit.
-C|<num>|::
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.
<num> is optional but it is the lower bound on the number of
alphanumeric characters that git must detect as moving
between files for it to associate those lines with the parent
commit.
-h, --help::
Show help message.

View File

@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision.
OPTIONS OPTIONS
------- -------
-l, --long:: include::blame-options.txt[]
Show long rev (Defaults off).
-t, --time::
Show raw timestamp (Defaults off).
-r, --rename::
Follow renames (Defaults on).
-S, --rev-file <revs-file>::
Use revs from revs-file instead of calling git-rev-list.
-h, --help::
Show help message.
SEE ALSO SEE ALSO
-------- --------

View File

@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file
SYNOPSIS SYNOPSIS
-------- --------
[verse] [verse]
'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>] 'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
[-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file> [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
[<rev> | --contents <file>] [--] <file>
DESCRIPTION DESCRIPTION
----------- -----------
@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
OPTIONS OPTIONS
------- -------
-c, --compatibility:: include::blame-options.txt[]
-c::
Use the same output mode as gitlink:git-annotate[1] (Default: off). Use the same output mode as gitlink:git-annotate[1] (Default: off).
-L n,m:: --score-debug::
Annotate only the specified line range (lines count from 1). Include debugging information related to the movement of
lines between files (see `-C`) and lines moved within a
-l, --long:: file (see `-M`). The first number listed is the score.
Show long rev (Default: off). This is the number of alphanumeric characters detected
to be moved between or within files. This must be above
-t, --time:: a certain threshold for git-blame to consider those lines
Show raw timestamp (Default: off). of code to have been moved.
-S, --rev-file <revs-file>::
Use revs from revs-file instead of calling gitlink:git-rev-list[1].
-f, --show-name:: -f, --show-name::
Show filename in the original commit. By default Show filename in the original commit. By default
@ -60,42 +60,6 @@ OPTIONS
-n, --show-number:: -n, --show-number::
Show line number in the original commit (Default: off). Show line number in the original commit (Default: off).
-p, --porcelain::
Show in a format designed for machine consumption.
--incremental::
Show the result incrementally in a format designed for
machine consumption.
--contents <file>::
When <rev> is not specified, the command annotates the
changes starting backwards from the working tree copy.
This flag makes the command pretend as if the working
tree copy has the contents of he named file (specify
`-` to make the command read from the standard input).
-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 THE PORCELAIN FORMAT
-------------------- --------------------

View File

@ -19,11 +19,11 @@
static char blame_usage[] = static char blame_usage[] =
"git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n" "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n"
" -c, --compatibility Use the same output mode as git-annotate (Default: off)\n" " -c Use the same output mode as git-annotate (Default: off)\n"
" -b Show blank SHA-1 for boundary commits (Default: off)\n" " -b Show blank SHA-1 for boundary commits (Default: off)\n"
" -l, --long Show long commit SHA1 (Default: off)\n" " -l Show long commit SHA1 (Default: off)\n"
" --root Do not treat root commits as boundaries (Default: off)\n" " --root Do not treat root commits as boundaries (Default: off)\n"
" -t, --time Show raw timestamp (Default: off)\n" " -t Show raw timestamp (Default: off)\n"
" -f, --show-name Show original filename (Default: auto)\n" " -f, --show-name Show original filename (Default: auto)\n"
" -n, --show-number Show original linenumber (Default: off)\n" " -n, --show-number Show original linenumber (Default: off)\n"
" -p, --porcelain Show in a format designed for machine consumption\n" " -p, --porcelain Show in a format designed for machine consumption\n"