From 635f4a30f0f73fcd3ed29c8d70be334689cc4082 Mon Sep 17 00:00:00 2001 From: Andrew Ruder Date: Mon, 16 Apr 2007 01:20:34 -0500 Subject: [PATCH] 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 Signed-off-by: Junio C Hamano --- Documentation/blame-options.txt | 67 +++++++++++++++++++++++++++++++++ Documentation/git-annotate.txt | 15 +------- Documentation/git-blame.txt | 64 +++++++------------------------ builtin-blame.c | 6 +-- 4 files changed, 85 insertions(+), 67 deletions(-) create mode 100644 Documentation/blame-options.txt diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt new file mode 100644 index 0000000000..331f161c77 --- /dev/null +++ b/Documentation/blame-options.txt @@ -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 :: + 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 :: + When 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. + + 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||:: + 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. + + 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. diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 7baf73111b..02dc4740d0 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -16,20 +16,7 @@ which introduced the line. Optionally annotate from a given revision. OPTIONS ------- --l, --long:: - Show long rev (Defaults off). - --t, --time:: - Show raw timestamp (Defaults off). - --r, --rename:: - Follow renames (Defaults on). - --S, --rev-file :: - Use revs from revs-file instead of calling git-rev-list. - --h, --help:: - Show help message. +include::blame-options.txt[] SEE ALSO -------- diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 5c9888d014..8f9439a6dd 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,8 +8,9 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S ] - [-M] [-C] [-C] [--since=] [ | --contents ] [--] +'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] + [-S ] [-M] [-C] [-C] [--since=] + [ | --contents ] [--] DESCRIPTION ----------- @@ -37,20 +38,19 @@ ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output OPTIONS ------- --c, --compatibility:: +include::blame-options.txt[] + +-c:: 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). - --l, --long:: - Show long rev (Default: off). - --t, --time:: - Show raw timestamp (Default: off). - --S, --rev-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 @@ -60,42 +60,6 @@ OPTIONS -n, --show-number:: 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 :: - When 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 -------------------- diff --git a/builtin-blame.c b/builtin-blame.c index bc86bda6c4..8919b028e6 100644 --- a/builtin-blame.c +++ b/builtin-blame.c @@ -19,11 +19,11 @@ static char blame_usage[] = "git-blame [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S ] [-M] [-C] [-C] [--contents ] [--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" -" -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" -" -t, --time Show raw timestamp (Default: off)\n" +" -t Show raw timestamp (Default: off)\n" " -f, --show-name Show original filename (Default: auto)\n" " -n, --show-number Show original linenumber (Default: off)\n" " -p, --porcelain Show in a format designed for machine consumption\n"