From 0d3c81546c38713ca17817d884eed8f9ae6ae88b Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 8 Nov 2006 01:33:41 +0000 Subject: [PATCH] Autogenerated HTML docs for v1.4.4-rc1 --- config.txt | 11 +- git-fetch-pack.html | 5 +- git-fetch-pack.txt | 3 +- git-index-pack.html | 77 ++++++- git-index-pack.txt | 52 ++++- git-pack-objects.html | 29 ++- git-pack-objects.txt | 17 ++ git-pickaxe.html | 516 ++++++++++++++++++++++++++++++++++++++++++ git-pickaxe.txt | 162 +++++++++++++ git-repo-config.html | 18 +- git-rev-parse.html | 12 +- git-rev-parse.txt | 13 +- git.html | 10 +- git.txt | 3 + 14 files changed, 911 insertions(+), 17 deletions(-) create mode 100644 git-pickaxe.html create mode 100644 git-pickaxe.txt diff --git a/config.txt b/config.txt index d9e73da2a..9d3c71c3b 100644 --- a/config.txt +++ b/config.txt @@ -301,7 +301,16 @@ imap:: The configuration variables in the 'imap' section are described in gitlink:git-imap-send[1]. -receive.denyNonFastforwads:: +receive.unpackLimit:: + If the number of objects received in a push is below this + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. + +receive.denyNonFastForwards:: If set to true, git-receive-pack will deny a ref update which is not a fast forward. Use this to prevent such an update via a push, even if that push is forced. This configuration variable is diff --git a/git-fetch-pack.html b/git-fetch-pack.html index 2543a7cad..99a307c4b 100644 --- a/git-fetch-pack.html +++ b/git-fetch-pack.html @@ -304,7 +304,8 @@ have a common ancestor commit.

Do not invoke git-unpack-objects on received data, but create a single packfile out of it instead, and store it - in the object database. + in the object database. If provided twice then the pack is + locked against repacking.

@@ -368,7 +369,7 @@ have a common ancestor commit.

diff --git a/git-fetch-pack.txt b/git-fetch-pack.txt index bff9aa693..3e6cd880b 100644 --- a/git-fetch-pack.txt +++ b/git-fetch-pack.txt @@ -32,7 +32,8 @@ OPTIONS -k:: Do not invoke 'git-unpack-objects' on received data, but create a single packfile out of it instead, and store it - in the object database. + in the object database. If provided twice then the pack is + locked against repacking. --exec=:: Use this to specify the path to 'git-upload-pack' on the diff --git a/git-index-pack.html b/git-index-pack.html index aaff699b5..a92d4d892 100644 --- a/git-index-pack.html +++ b/git-index-pack.html @@ -272,7 +272,8 @@ git-index-pack(1) Manual Page

SYNOPSIS

-

git-index-pack [-o <index-file>] <pack-file>

+

git-index-pack [-v] [-o <index-file>] <pack-file> +git-index-pack --stdin [--fix-thin] [--keep] [-v] [-o <index-file>] [<pack-file>]

DESCRIPTION

@@ -285,6 +286,14 @@ objects/pack/ directory of a git repository.

+-v +
+
+

+ Be verbose about what is going on, including progress status. +

+
+
-o <index-file>
@@ -297,8 +306,72 @@ objects/pack/ directory of a git repository.

with .pack).

+
+--stdin +
+
+

+ When this flag is provided, the pack is read from stdin + instead and a copy is then written to <pack-file>. If + <pack-file> is not specified, the pack is written to + objects/pack/ directory of the current git repository with + a default name determined from the pack content. If + <pack-file> is not specified consider using --keep to + prevent a race condition between this process and + :git-repack(1) . +

+
+
+--fix-thin +
+
+

+ It is possible for git-pack-objects(1) to build + "thin" pack, which records objects in deltified form based on + objects not included in the pack to reduce network traffic. + Those objects are expected to be present on the receiving end + and they must be included in the pack for that pack to be self + contained and indexable. Without this option any attempt to + index a thin pack will fail. This option only makes sense in + conjunction with --stdin. +

+
+
+--keep +
+
+

+ Before moving the index into its final destination + create an empty .keep file for the associated pack file. + This option is usually necessary with --stdin to prevent a + simultaneous git-repack(1) process from deleting + the newly constructed pack and index before refs can be + updated to use objects contained in the pack. +

+
+
+--keep=why +
+
+

+ Like --keep create a .keep file before moving the index into + its final destination, but rather than creating an empty file + place why followed by an LF into the .keep file. The why + message can later be searched for within all .keep files to + locate any which have outlived their usefulness. +

+
+

Note

+
+

Once the index has been created, the list of object names is sorted +and the SHA1 hash of that list is printed to stdout. If --stdin was +also used then this is prefixed by either "pack\t", or "keep\t" if a +new .keep file was successfully created. This is useful to remove a +.keep file used as a lock to prevent the race with git-repack(1) +mentioned above.

+

Author

Written by Sergey Vlasov <vsu@altlinux.ru>

@@ -313,7 +386,7 @@ objects/pack/ directory of a git repository.

diff --git a/git-index-pack.txt b/git-index-pack.txt index 71ce55727..2229ee86b 100644 --- a/git-index-pack.txt +++ b/git-index-pack.txt @@ -8,7 +8,8 @@ git-index-pack - Build pack index file for an existing packed archive SYNOPSIS -------- -'git-index-pack' [-o ] +'git-index-pack' [-v] [-o ] +'git-index-pack' --stdin [--fix-thin] [--keep] [-v] [-o ] [] DESCRIPTION @@ -21,6 +22,9 @@ objects/pack/ directory of a git repository. OPTIONS ------- +-v:: + Be verbose about what is going on, including progress status. + -o :: Write the generated pack index into the specified file. Without this option the name of pack index @@ -29,6 +33,52 @@ OPTIONS fails if the name of packed archive does not end with .pack). +--stdin:: + When this flag is provided, the pack is read from stdin + instead and a copy is then written to . If + is not specified, the pack is written to + objects/pack/ directory of the current git repository with + a default name determined from the pack content. If + is not specified consider using --keep to + prevent a race condition between this process and + gitlink::git-repack[1] . + +--fix-thin:: + It is possible for gitlink:git-pack-objects[1] to build + "thin" pack, which records objects in deltified form based on + objects not included in the pack to reduce network traffic. + Those objects are expected to be present on the receiving end + and they must be included in the pack for that pack to be self + contained and indexable. Without this option any attempt to + index a thin pack will fail. This option only makes sense in + conjunction with --stdin. + +--keep:: + Before moving the index into its final destination + create an empty .keep file for the associated pack file. + This option is usually necessary with --stdin to prevent a + simultaneous gitlink:git-repack[1] process from deleting + the newly constructed pack and index before refs can be + updated to use objects contained in the pack. + +--keep='why':: + Like --keep create a .keep file before moving the index into + its final destination, but rather than creating an empty file + place 'why' followed by an LF into the .keep file. The 'why' + message can later be searched for within all .keep files to + locate any which have outlived their usefulness. + + +Note +---- + +Once the index has been created, the list of object names is sorted +and the SHA1 hash of that list is printed to stdout. If --stdin was +also used then this is prefixed by either "pack\t", or "keep\t" if a +new .keep file was successfully created. This is useful to remove a +.keep file used as a lock to prevent the race with gitlink:git-repack[1] +mentioned above. + Author ------ diff --git a/git-pack-objects.html b/git-pack-objects.html index 9eaf45055..63d2fd54b 100644 --- a/git-pack-objects.html +++ b/git-pack-objects.html @@ -404,6 +404,33 @@ base-name

+--progress +
+
+

+ Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if + the standard error stream is not directed to a terminal. +

+
+
+--all-progress +
+
+

+ When --stdout is specified then progress report is + displayed during the object count and deltification phases + but inhibited during the write-out phase. The reason is + that in some cases the output stream is directly linked + to another command which may wish to display progress + status of its own as it processes incoming pack data. + This flag is like --progress except that it forces progress + report for the write-out phase as well even if --stdout is + used. +

+
+
-q
@@ -462,7 +489,7 @@ base-name diff --git a/git-pack-objects.txt b/git-pack-objects.txt index 5ebe34eeb..fdc6f9728 100644 --- a/git-pack-objects.txt +++ b/git-pack-objects.txt @@ -99,6 +99,23 @@ base-name:: Only create a packed archive if it would contain at least one object. +--progress:: + Progress status is reported on the standard error stream + by default when it is attached to a terminal, unless -q + is specified. This flag forces progress status even if + the standard error stream is not directed to a terminal. + +--all-progress:: + When --stdout is specified then progress report is + displayed during the object count and deltification phases + but inhibited during the write-out phase. The reason is + that in some cases the output stream is directly linked + to another command which may wish to display progress + status of its own as it processes incoming pack data. + This flag is like --progress except that it forces progress + report for the write-out phase as well even if --stdout is + used. + -q:: This flag makes the command not to report its progress on the standard error stream. diff --git a/git-pickaxe.html b/git-pickaxe.html new file mode 100644 index 000000000..877962243 --- /dev/null +++ b/git-pickaxe.html @@ -0,0 +1,516 @@ + + + + + + +git-pickaxe(1) + + + +

SYNOPSIS

+
+
+
git-pickaxe [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S <revs-file>] + [-M] [-C] [-C] [--since=<date>] [<rev>] [--] <file>
+
+

DESCRIPTION

+
+

Annotates each line in the given file with information from the revision which +last modified the line. Optionally, start annotating from the given revision.

+

Also it can limit the range of lines annotated.

+

This report doesn't tell you anything about lines which have been deleted or +replaced; you need to use a tool such as git-diff(1) or the "pickaxe" +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 +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:

+
+
+
$ git log --pretty=oneline -S'blame_usage'
+5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
+ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output
+
+
+

OPTIONS

+
+
+
+-c, --compatibility +
+
+

+ Use the same output mode as 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 <revs-file> +
+
+

+ Use revs from revs-file instead of calling git-rev-list(1). +

+
+
+-f, --show-name +
+
+

+ Show filename in the original commit. By default + filename is shown if there is any line that came from a + file with different name, due to rename detection. +

+
+
+-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 +header at the minumum 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; +

    +
    • +
  • +

    +the line number of the line in the final file; +

    +
    • +
  • +

    +on a line that starts a group of line from a different + commit than the previous one, the number of lines in this + group. On subsequent lines this field is absent. +

    +
    • +
+

This header line is followed by the following information +at least once for each commit:

+
    +
  • +

    +author name ("author"), email ("author-mail"), time + ("author-time"), and timezone ("author-tz"); similarly + for committer. +

    +
    • +
  • +

    +filename in the commit the line is attributed to. +

    +
    • +
  • +

    +the first line of the commit log message ("summary"). +

    +
    • +
+

The contents of the actual line is output after the above +header, prefixed by a TAB. This is to allow adding more +header elements later.

+
+

SPECIFIYING 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 +ll. 40-60 for file foo, you can use -L option like this:

+
+
+
git pickaxe -L 40,60 foo
+
+

When you are not interested in changes older than the version +v2.6.18, or changes older than 3 weeks, you can use revision +range specifiers similar to git-rev-list:

+
+
+
git pickaxe v2.6.18.. -- foo
+git pickaxe --since=3.weeks -- foo
+
+

When revision range specifiers are used to limit the annotation, +lines that have not changed since the range boundary (either the +commit v2.6.18 or the most recent commit that is more than 3 +weeks old in the above example) are blamed for that range +boundary commit.

+

A particularly useful way is to see if an added file have lines +created by copy-and-paste from existing files. Sometimes this +indicates that the developer was being sloppy and did not +refactor the code properly. You can first find the commit that +introduced the file with:

+
+
+
git log --diff-filter=A --pretty=short -- foo
+
+

and then annotate the change between the commit and its +parents, using commit^! notation:

+
+
+
git pickaxe -C -C -f $commit^! -- foo
+
+
+

SEE ALSO

+
+

git-blame(1)

+
+

AUTHOR

+
+

Written by Junio C Hamano <junkio@cox.net>

+
+

GIT

+
+

Part of the git(7) suite

+
+ + + diff --git a/git-pickaxe.txt b/git-pickaxe.txt new file mode 100644 index 000000000..c08fdec19 --- /dev/null +++ b/git-pickaxe.txt @@ -0,0 +1,162 @@ +git-pickaxe(1) +============== + +NAME +---- +git-pickaxe - Show what revision and author last modified each line of a file + +SYNOPSIS +-------- +[verse] +'git-pickaxe' [-c] [-l] [-t] [-f] [-n] [-p] [-L n,m] [-S ] + [-M] [-C] [-C] [--since=] [] [--] + +DESCRIPTION +----------- + +Annotates each line in the given file with information from the revision which +last modified the line. Optionally, start annotating from the given revision. + +Also it can limit the range of lines annotated. + +This report doesn't tell you anything about lines which have been deleted or +replaced; you need to use a tool such as gitlink:git-diff[1] or the "pickaxe" +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 +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: + +----------------------------------------------------------------------------- +$ git log --pretty=oneline -S'blame_usage' +5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S +ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output +----------------------------------------------------------------------------- + +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). + +-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]. + +-f, --show-name:: + Show filename in the original commit. By default + filename is shown if there is any line that came from a + file with different name, due to rename detection. + +-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 +header at the minumum 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; +- the line number of the line in the final file; +- on a line that starts a group of line from a different + commit than the previous one, the number of lines in this + group. On subsequent lines this field is absent. + +This header line is followed by the following information +at least once for each commit: + +- author name ("author"), email ("author-mail"), time + ("author-time"), and timezone ("author-tz"); similarly + for committer. +- filename in the commit the line is attributed to. +- the first line of the commit log message ("summary"). + +The contents of the actual line is output after the above +header, prefixed by a TAB. This is to allow adding more +header elements later. + + +SPECIFIYING 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 +ll. 40-60 for file `foo`, you can use `-L` option like this: + + git pickaxe -L 40,60 foo + +When you are not interested in changes older than the version +v2.6.18, or changes older than 3 weeks, you can use revision +range specifiers similar to `git-rev-list`: + + git pickaxe v2.6.18.. -- foo + git pickaxe --since=3.weeks -- foo + +When revision range specifiers are used to limit the annotation, +lines that have not changed since the range boundary (either the +commit v2.6.18 or the most recent commit that is more than 3 +weeks old in the above example) are blamed for that range +boundary commit. + +A particularly useful way is to see if an added file have lines +created by copy-and-paste from existing files. Sometimes this +indicates that the developer was being sloppy and did not +refactor the code properly. You can first find the commit that +introduced the file with: + + git log --diff-filter=A --pretty=short -- foo + +and then annotate the change between the commit and its +parents, using `commit{caret}!` notation: + + git pickaxe -C -C -f $commit^! -- foo + + +SEE ALSO +-------- +gitlink:git-blame[1] + +AUTHOR +------ +Written by Junio C Hamano + +GIT +--- +Part of the gitlink:git[7] suite diff --git a/git-repo-config.html b/git-repo-config.html index aa53ec579..5dd623426 100644 --- a/git-repo-config.html +++ b/git-repo-config.html @@ -1066,7 +1066,21 @@ imap

-receive.denyNonFastforwads +receive.unpackLimit +
+
+

+ If the number of objects received in a push is below this + limit then the objects will be unpacked into loose object + files. However if the number of received objects equals or + exceeds this limit then the received pack will be stored as + a pack, after adding any missing delta bases. Storing the + pack from a push can make the push operation complete faster, + especially on slow filesystems. +

+
+
+receive.denyNonFastForwards

@@ -1092,7 +1106,7 @@ receive.denyNonFastforwads

diff --git a/git-rev-parse.html b/git-rev-parse.html index 987ebc956..d452f1ee4 100644 --- a/git-rev-parse.html +++ b/git-rev-parse.html @@ -649,7 +649,11 @@ of r1 and r2 and is defined as "r1 r2 --not $(git-merge-base --all r1 r2)". It it the set of commits that are reachable from either one of r1 or r2 but not from both.

-

Here are a few examples:

+

Two other shorthands for naming a set that is formed by a commit +and its parent commits exists. r1^@ notation means all +parents of r1. r1^! includes commit r1 but excludes +its all parents.

+

Here are a handful examples:

D                A B D
@@ -657,7 +661,9 @@ D F              A B C D F
 ^A G             B D
 ^A F             B C F
 G...I            C D F G I
-^B G I           C D F G I
+^B G I C D F G I +F^@ A B C +F^! H D F H

Author

@@ -675,7 +681,7 @@ Junio C Hamano <junkio@cox.net>

diff --git a/git-rev-parse.txt b/git-rev-parse.txt index ed938aafb..4eaf5a0d1 100644 --- a/git-rev-parse.txt +++ b/git-rev-parse.txt @@ -239,14 +239,21 @@ of `r1` and `r2` and is defined as It it the set of commits that are reachable from either one of `r1` or `r2` but not from both. -Here are a few examples: +Two other shorthands for naming a set that is formed by a commit +and its parent commits exists. `r1{caret}@` notation means all +parents of `r1`. `r1{caret}!` includes commit `r1` but excludes +its all parents. + +Here are a handful examples: D A B D D F A B C D F - ^A G B D + ^A G B D ^A F B C F G...I C D F G I - ^B G I C D F G I + ^B G I C D F G I + F^@ A B C + F^! H D F H Author ------ diff --git a/git.html b/git.html index e5a6611fa..231cc0d8a 100644 --- a/git.html +++ b/git.html @@ -817,6 +817,14 @@ ancillary user utilities.

+git-pickaxe(1) +
+
+

+ Find out where each line in a file came from. +

+
+
git-check-ref-format(1)
@@ -2206,7 +2214,7 @@ contributors on the git-list <git@vger.kernel.org>.

diff --git a/git.txt b/git.txt index 4ce4f8d1c..4facf2309 100644 --- a/git.txt +++ b/git.txt @@ -254,6 +254,9 @@ gitlink:git-annotate[1]:: gitlink:git-blame[1]:: Blame file lines on commits. +gitlink:git-pickaxe[1]:: + Find out where each line in a file came from. + gitlink:git-check-ref-format[1]:: Make sure ref name is well formed. -- 2.26.2