@matheusbsbs / matheus-bagliano / commits / 635f4a30f0
Fork 0

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>

Andrew Ruder committed Apr 16, 2007 at 01:20 UTC 635f4a30f0f73fcd3ed29c8d70be334689cc4082
4 files changed +85 -67
Documentation/blame-options.txt new
+67
@@ -0,0 +1,67 @@
1 +-b::
2 + Show blank SHA-1 for boundary commits. This can also
3 + be controlled via the `blame.blankboundary` config option.
4 +
5 +--root::
6 + Do not treat root commits as boundaries. This can also be
7 + controlled via the `blame.showroot` config option.
8 +
9 +--show-stats::
10 + Include additional statistics at the end of blame output.
11 +
12 +-L n,m::
13 + Annotate only the specified line range (lines count from 1).
14 +
15 +-l::
16 + Show long rev (Default: off).
17 +
18 +-t::
19 + Show raw timestamp (Default: off).
20 +
21 +-S <revs-file>::
22 + Use revs from revs-file instead of calling gitlink:git-rev-list[1].
23 +
24 +-p, --porcelain::
25 + Show in a format designed for machine consumption.
26 +
27 +--incremental::
28 + Show the result incrementally in a format designed for
29 + machine consumption.
30 +
31 +--contents <file>::
32 + When <rev> is not specified, the command annotates the
33 + changes starting backwards from the working tree copy.
34 + This flag makes the command pretend as if the working
35 + tree copy has the contents of he named file (specify
36 + `-` to make the command read from the standard input).
37 +
38 +-M|<num>|::
39 + Detect moving lines in the file as well. When a commit
40 + moves a block of lines in a file (e.g. the original file
41 + has A and then B, and the commit changes it to B and
42 + then A), traditional 'blame' algorithm typically blames
43 + the lines that were moved up (i.e. B) to the parent and
44 + assigns blame to the lines that were moved down (i.e. A)
45 + to the child commit. With this option, both groups of lines
46 + are blamed on the parent.
47 +
48 + <num> is optional but it is the lower bound on the number of
49 + alphanumeric characters that git must detect as moving
50 + within a file for it to associate those lines with the parent
51 + commit.
52 +
53 +-C|<num>|::
54 + In addition to `-M`, detect lines copied from other
55 + files that were modified in the same commit. This is
56 + useful when you reorganize your program and move code
57 + around across files. When this option is given twice,
58 + the command looks for copies from all other files in the
59 + parent for the commit that creates the file in addition.
60 +
61 + <num> is optional but it is the lower bound on the number of
62 + alphanumeric characters that git must detect as moving
63 + between files for it to associate those lines with the parent
64 + commit.
65 +
66 +-h, --help::
67 + Show help message.
Documentation/git-annotate.txt
+1 -14
@@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision.
16
17 OPTIONS
18 -------
19 --l, --long::
20 - Show long rev (Defaults off).
21 -
22 --t, --time::
23 - Show raw timestamp (Defaults off).
24 -
25 --r, --rename::
26 - Follow renames (Defaults on).
27 -
28 --S, --rev-file <revs-file>::
29 - Use revs from revs-file instead of calling git-rev-list.
30 -
31 --h, --help::
32 - Show help message.
19 +include::blame-options.txt[]
20
21 SEE ALSO
22 --------
Documentation/git-blame.txt
+14 -50
@@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file
8 SYNOPSIS
9 --------
10 [verse]
11 -'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>]
12 - [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file>
11 +'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m]
12 + [-S <revs-file>] [-M] [-C] [-C] [--since=<date>]
13 + [<rev> | --contents <file>] [--] <file>
14
15 DESCRIPTION
16 -----------
@@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
38
39 OPTIONS
40 -------
40 --c, --compatibility::
41 - Use the same output mode as gitlink:git-annotate[1] (Default: off).
42 -
43 --L n,m::
44 - Annotate only the specified line range (lines count from 1).
45 -
46 --l, --long::
47 - Show long rev (Default: off).
41 +include::blame-options.txt[]
42
49 --t, --time::
50 - Show raw timestamp (Default: off).
43 +-c::
44 + Use the same output mode as gitlink:git-annotate[1] (Default: off).
45
52 --S, --rev-file <revs-file>::
53 - Use revs from revs-file instead of calling gitlink:git-rev-list[1].
46 +--score-debug::
47 + Include debugging information related to the movement of
48 + lines between files (see `-C`) and lines moved within a
49 + file (see `-M`). The first number listed is the score.
50 + This is the number of alphanumeric characters detected
51 + to be moved between or within files. This must be above
52 + a certain threshold for git-blame to consider those lines
53 + of code to have been moved.
54
55 -f, --show-name::
56 Show filename in the original commit. By default
@@ -60,42 +60,6 @@ OPTIONS
60 -n, --show-number::
61 Show line number in the original commit (Default: off).
62
63 --p, --porcelain::
64 - Show in a format designed for machine consumption.
65 -
66 ---incremental::
67 - Show the result incrementally in a format designed for
68 - machine consumption.
69 -
70 ---contents <file>::
71 - When <rev> is not specified, the command annotates the
72 - changes starting backwards from the working tree copy.
73 - This flag makes the command pretend as if the working
74 - tree copy has the contents of he named file (specify
75 - `-` to make the command read from the standard input).
76 -
77 --M::
78 - Detect moving lines in the file as well. When a commit
79 - moves a block of lines in a file (e.g. the original file
80 - has A and then B, and the commit changes it to B and
81 - then A), traditional 'blame' algorithm typically blames
82 - the lines that were moved up (i.e. B) to the parent and
83 - assigns blame to the lines that were moved down (i.e. A)
84 - to the child commit. With this option, both groups of
85 - lines are blamed on the parent.
86 -
87 --C::
88 - In addition to `-M`, detect lines copied from other
89 - files that were modified in the same commit. This is
90 - useful when you reorganize your program and move code
91 - around across files. When this option is given twice,
92 - the command looks for copies from all other files in the
93 - parent for the commit that creates the file in addition.
94 -
95 --h, --help::
96 - Show help message.
97 -
98 -
63 THE PORCELAIN FORMAT
64 --------------------
65
builtin-blame.c
+3 -3
@@ -19,11 +19,11 @@
19
20 static char blame_usage[] =
21 "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--contents <filename>] [--incremental] [commit] [--] file\n"
22 -" -c, --compatibility Use the same output mode as git-annotate (Default: off)\n"
22 +" -c Use the same output mode as git-annotate (Default: off)\n"
23 " -b Show blank SHA-1 for boundary commits (Default: off)\n"
24 -" -l, --long Show long commit SHA1 (Default: off)\n"
24 +" -l Show long commit SHA1 (Default: off)\n"
25 " --root Do not treat root commits as boundaries (Default: off)\n"
26 -" -t, --time Show raw timestamp (Default: off)\n"
26 +" -t Show raw timestamp (Default: off)\n"
27 " -f, --show-name Show original filename (Default: auto)\n"
28 " -n, --show-number Show original linenumber (Default: off)\n"
29 " -p, --porcelain Show in a format designed for machine consumption\n"