index 9d20a4ff19bc42497b15220cb3ad5a04594f6753..cb4e562004e58439a0055d9ed6a6bdab249dfcdc 100644 (file)
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
- 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
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
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
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
: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
------------------------------------------------
: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`
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
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
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
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:
------------------------------------------------