git-tar-tree: no more void pointer arithmetic

[git.git] / Documentation / diffcore.txt

diff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt
index 7c2168a..cb4e562 100644 (file)
--- a/Documentation/diffcore.txt
+++ b/Documentation/diffcore.txt
@@ -6,13 +6,12 @@ June 2005
 Introduction
 ------------
 
 Introduction
 ------------
 

-The diff commands git-diff-index, git-diff-files, and
-git-diff-tree can be told to manipulate differences they find
-in unconventional ways before showing diff(1) output.  The
-manipulation is collectively called "diffcore transformation".
-This short note describes what they are and how to use them to
-produce diff outputs that are easier to understand than the
-conventional kind.
+The diff commands git-diff-index, git-diff-files, git-diff-tree, and
+git-diff-stages can be told to manipulate differences they find in
+unconventional ways before showing diff(1) output.  The manipulation
+is collectively called "diffcore transformation".  This short note
+describes what they are and how to use them to produce diff outputs
+that are easier to understand than the conventional kind.

 
 
 The chain of operation
 
 
 The chain of operation


@@ -29,7 +28,10 @@ files:
  - git-diff-files compares contents of the index file and the
    working directory;
 
  - git-diff-files compares contents of the index file and the
    working directory;
 

- - git-diff-tree compares contents of two "tree" objects.
+ - git-diff-tree compares contents of two "tree" objects;
+
+ - git-diff-stages compares contents of blobs at two stages in an
+   unmerged index file.

 
 In all of these cases, the commands themselves compare
 corresponding paths in the two sets of files.  The result of
 
 In all of these cases, the commands themselves compare
 corresponding paths in the two sets of files.  The result of


@@ -65,14 +67,23 @@ format sections of the manual for git-diff-\* commands) or
 diff-patch format.
 
 
 diff-patch format.
 
 

-diffcore-pathspec
------------------
+diffcore-pathspec: For Ignoring Files Outside Our Consideration
+---------------------------------------------------------------

 
 The first transformation in the chain is diffcore-pathspec, and
 is controlled by giving the pathname parameters to the
 git-diff-* commands on the command line.  The pathspec is used
 to limit the world diff operates in.  It removes the filepairs
 
 The first transformation in the chain is diffcore-pathspec, and
 is controlled by giving the pathname parameters to the
 git-diff-* commands on the command line.  The pathspec is used
 to limit the world diff operates in.  It removes the filepairs

-outside the specified set of pathnames.
+outside the specified set of pathnames.  E.g. If the input set 
+of filepairs included:
+
+------------------------------------------------
+:100644 100644 bcd1234... 0123456... M junkfile
+------------------------------------------------
+
+but the command invocation was "git-diff-files myfile", then the
+junkfile entry would be removed from the list because only "myfile"
+is under consideration.

 
 Implementation note.  For performance reasons, git-diff-tree
 uses the pathname parameters on the command line to cull set of
 
 Implementation note.  For performance reasons, git-diff-tree
 uses the pathname parameters on the command line to cull set of


@@ -80,8 +91,8 @@ filepairs it feeds the diffcore mechanism itself, and does not
 use diffcore-pathspec, but the end result is the same.
 
 
 use diffcore-pathspec, but the end result is the same.
 
 

-diffcore-break
---------------
+diffcore-break: For Splitting Up "Complete Rewrites"
+----------------------------------------------------

 
 The second transformation in the chain is diffcore-break, and is
 controlled by the -B option to the git-diff-* commands.  This is
 
 The second transformation in the chain is diffcore-break, and is
 controlled by the -B option to the git-diff-* commands.  This is


@@ -115,8 +126,8 @@ the original is used), and can be customized by giving a number
 after "-B" option (e.g. "-B75" to tell it to use 75%).
 
 
 after "-B" option (e.g. "-B75" to tell it to use 75%).
 
 

-diffcore-rename
----------------
+diffcore-rename: For Detection Renames and Copies
+-------------------------------------------------

 
 This transformation is used to detect renames and copies, and is
 controlled by the -M option (to detect renames) and the -C option
 
 This transformation is used to detect renames and copies, and is
 controlled by the -M option (to detect renames) and the -C option


@@ -136,16 +147,16 @@ merges these filepairs and creates:
 :100644 100644 0123456... 0123456... R100 fileX file0
 ------------------------------------------------
 
 :100644 100644 0123456... 0123456... R100 fileX file0
 ------------------------------------------------
 

-When the "-C" option is used, the original contents of modified
-files and contents of unchanged files are considered as
-candidates of the source files in rename/copy operation, in
-addition to the deleted files.  If the input were like these
-filepairs, that talk about a modified file fileY and a newly
+When the "-C" option is used, the original contents of modified files,
+and deleted files (and also unmodified files, if the
+"\--find-copies-harder" option is used) are considered as candidates
+of the source files in rename/copy operation.  If the input were like
+these filepairs, that talk about a modified file fileY and a newly

 created file file0:
 
 ------------------------------------------------
 :100644 100644 0123456... 1234567... M fileY
 created file file0:
 
 ------------------------------------------------
 :100644 100644 0123456... 1234567... M fileY

-:000000 100644 0000000... 0123456... A file0
+:000000 100644 0000000... bcd3456... A file0

 ------------------------------------------------
 
 the original contents of fileY and the resulting contents of
 ------------------------------------------------
 
 the original contents of fileY and the resulting contents of


@@ -154,14 +165,14 @@ changed to:
 
 ------------------------------------------------
 :100644 100644 0123456... 1234567... M fileY
 
 ------------------------------------------------
 :100644 100644 0123456... 1234567... M fileY

-:100644 100644 0123456... 0123456... C100 fileY file0
+:100644 100644 0123456... bcd3456... C100 fileY file0

 ------------------------------------------------
 
 In both rename and copy detection, the same "extent of changes"
 algorithm used in diffcore-break is used to determine if two
 files are "similar enough", and can be customized to use
 ------------------------------------------------
 
 In both rename and copy detection, the same "extent of changes"
 algorithm used in diffcore-break is used to determine if two
 files are "similar enough", and can be customized to use

-similarity score different from the default 50% by giving a
-number after "-M" or "-C" option (e.g. "-M8" to tell it to use
+a similarity score different from the default of 50% by giving a
+number after the "-M" or "-C" option (e.g. "-M8" to tell it to use

 8/10 = 80%).
 
 Note.  When the "-C" option is used with `\--find-copies-harder`
 8/10 = 80%).
 
 Note.  When the "-C" option is used with `\--find-copies-harder`


@@ -173,8 +184,8 @@ git-diff-\* commands can detect copies only if the file that was
 copied happened to have been modified in the same changeset.
 
 
 copied happened to have been modified in the same changeset.
 
 

-diffcore-merge-broken
----------------------
+diffcore-merge-broken: For Putting "Complete Rewrites" Back Together
+--------------------------------------------------------------------

 
 This transformation is used to merge filepairs broken by
 diffcore-break, and not transformed into rename/copy by
 
 This transformation is used to merge filepairs broken by
 diffcore-break, and not transformed into rename/copy by


@@ -215,8 +226,8 @@ prefixed with '-', followed by the entire contents of new
 version prefixed with '+'.
 
 
 version prefixed with '+'.
 
 

-diffcore-pickaxe
-----------------
+diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
+---------------------------------------------------------------------

 
 This transformation is used to find filepairs that represent
 changes that touch a specified string, and is controlled by the
 
 This transformation is used to find filepairs that represent
 changes that touch a specified string, and is controlled by the


@@ -230,7 +241,7 @@ string appeared in this changeset".  It also checks for the
 opposite case that loses the specified string.
 
 When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves
 opposite case that loses the specified string.
 
 When `\--pickaxe-all` is not in effect, diffcore-pickaxe leaves

-only such filepairs that touches the specified string in its
+only such filepairs that touch the specified string in its

 output.  When `\--pickaxe-all` is used, diffcore-pickaxe leaves all
 filepairs intact if there is such a filepair, or makes the
 output empty otherwise.  The latter behaviour is designed to
 output.  When `\--pickaxe-all` is used, diffcore-pickaxe leaves all
 filepairs intact if there is such a filepair, or makes the
 output empty otherwise.  The latter behaviour is designed to


@@ -238,19 +249,19 @@ make reviewing of the changes in the context of the whole
 changeset easier.
 
 
 changeset easier.
 
 

-diffcore-order
---------------
+diffcore-order: For Sorting the Output Based on Filenames
+---------------------------------------------------------

 
 This is used to reorder the filepairs according to the user's
 (or project's) taste, and is controlled by the -O option to the
 git-diff-* commands.
 
 
 This is used to reorder the filepairs according to the user's
 (or project's) taste, and is controlled by the -O option to the
 git-diff-* commands.
 

-This takes a text file each of whose line is a shell glob
+This takes a text file each of whose lines is a shell glob

 pattern.  Filepairs that match a glob pattern on an earlier line
 in the file are output before ones that match a later line, and
 filepairs that do not match any glob pattern are output last.
 
 pattern.  Filepairs that match a glob pattern on an earlier line
 in the file are output before ones that match a later line, and
 filepairs that do not match any glob pattern are output last.
 

-As an example, typical orderfile for the core git probably
+As an example, a typical orderfile for the core git probably

 would look like this:
 
 ------------------------------------------------
 would look like this:
 
 ------------------------------------------------