--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>\r
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
+\r
+<article lang="en" id="gitdiffcore(7)">\r
+<articleinfo>\r
+ <title>gitdiffcore(7)</title>\r
+ <indexterm>\r
+ <primary>gitdiffcore(7)</primary>\r
+ </indexterm>\r
+</articleinfo>\r
+<simplesect id="_name">\r
+<title>NAME</title>\r
+<simpara>gitdiffcore - Tweaking diff output (June 2005)</simpara>\r
+</simplesect>\r
+<simplesect id="_synopsis">\r
+<title>SYNOPSIS</title>\r
+<simpara><emphasis>git diff</emphasis> *</simpara>\r
+</simplesect>\r
+<simplesect id="_description">\r
+<title>DESCRIPTION</title>\r
+<simpara>The diff commands <emphasis>git-diff-index</emphasis>, <emphasis>git-diff-files</emphasis>, and <emphasis>git-diff-tree</emphasis>\r
+can be told to manipulate differences they find in\r
+unconventional ways before showing <emphasis>diff</emphasis> output. The manipulation\r
+is collectively called "diffcore transformation". This short note\r
+describes what they are and how to use them to produce <emphasis>diff</emphasis> output\r
+that is easier to understand than the conventional kind.</simpara>\r
+</simplesect>\r
+<simplesect id="_the_chain_of_operation">\r
+<title>The chain of operation</title>\r
+<simpara>The <emphasis>git-diff-*</emphasis> family works by first comparing two sets of\r
+files:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+<emphasis>git-diff-index</emphasis> compares contents of a "tree" object and the\r
+ working directory (when <emphasis>--cached</emphasis> flag is not used) or a\r
+ "tree" object and the index file (when <emphasis>--cached</emphasis> flag is\r
+ used);\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+<emphasis>git-diff-files</emphasis> compares contents of the index file and the\r
+ working directory;\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+<emphasis>git-diff-tree</emphasis> compares contents of two "tree" objects;\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+<simpara>In all of these cases, the commands themselves first optionally limit\r
+the two sets of files by any pathspecs given on their command-lines,\r
+and compare corresponding paths in the two resulting sets of files.</simpara>\r
+<simpara>The pathspecs are used to limit the world diff operates in. They remove\r
+the filepairs outside the specified sets of pathnames. E.g. If the\r
+input set of filepairs included:</simpara>\r
+<literallayout>:100644 100644 bcd1234... 0123456... M junkfile</literallayout>\r
+<simpara>but the command invocation was <literal>git diff-files myfile</literal>, then the\r
+junkfile entry would be removed from the list because only "myfile"\r
+is under consideration.</simpara>\r
+<simpara>The result of comparison is passed from these commands to what is\r
+internally called "diffcore", in a format similar to what is output\r
+when the -p option is not used. E.g.</simpara>\r
+<literallayout>in-place edit :100644 100644 bcd1234... 0123456... M file0\r
+create :000000 100644 0000000... 1234567... A file4\r
+delete :100644 000000 1234567... 0000000... D file5\r
+unmerged :000000 000000 0000000... 0000000... U file6</literallayout>\r
+<simpara>The diffcore mechanism is fed a list of such comparison results\r
+(each of which is called "filepair", although at this point each\r
+of them talks about a single file), and transforms such a list\r
+into another list. There are currently 5 such transformations:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+diffcore-break\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+diffcore-rename\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+diffcore-merge-broken\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+diffcore-pickaxe\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+diffcore-order\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+<simpara>These are applied in sequence. The set of filepairs <emphasis>git-diff-*</emphasis>\r
+commands find are used as the input to diffcore-break, and\r
+the output from diffcore-break is used as the input to the\r
+next transformation. The final result is then passed to the\r
+output routine and generates either diff-raw format (see Output\r
+format sections of the manual for <emphasis>git-diff-*</emphasis> commands) or\r
+diff-patch format.</simpara>\r
+</simplesect>\r
+<simplesect id="_diffcore_break_for_splitting_up_complete_rewrites">\r
+<title>diffcore-break: For Splitting Up "Complete Rewrites"</title>\r
+<simpara>The second transformation in the chain is diffcore-break, and is\r
+controlled by the -B option to the <emphasis>git-diff-*</emphasis> commands. This is\r
+used to detect a filepair that represents "complete rewrite" and\r
+break such filepair into two filepairs that represent delete and\r
+create. E.g. If the input contained this filepair:</simpara>\r
+<literallayout>:100644 100644 bcd1234... 0123456... M file0</literallayout>\r
+<simpara>and if it detects that the file "file0" is completely rewritten,\r
+it changes it to:</simpara>\r
+<literallayout>:100644 000000 bcd1234... 0000000... D file0\r
+:000000 100644 0000000... 0123456... A file0</literallayout>\r
+<simpara>For the purpose of breaking a filepair, diffcore-break examines\r
+the extent of changes between the contents of the files before\r
+and after modification (i.e. the contents that have "bcd1234…"\r
+and "0123456…" as their SHA1 content ID, in the above\r
+example). The amount of deletion of original contents and\r
+insertion of new material are added together, and if it exceeds\r
+the "break score", the filepair is broken into two. The break\r
+score defaults to 50% of the size of the smaller of the original\r
+and the result (i.e. if the edit shrinks the file, the size of\r
+the result is used; if the edit lengthens the file, the size of\r
+the original is used), and can be customized by giving a number\r
+after "-B" option (e.g. "-B75" to tell it to use 75%).</simpara>\r
+</simplesect>\r
+<simplesect id="_diffcore_rename_for_detection_renames_and_copies">\r
+<title>diffcore-rename: For Detection Renames and Copies</title>\r
+<simpara>This transformation is used to detect renames and copies, and is\r
+controlled by the -M option (to detect renames) and the -C option\r
+(to detect copies as well) to the <emphasis>git-diff-*</emphasis> commands. If the\r
+input contained these filepairs:</simpara>\r
+<literallayout>:100644 000000 0123456... 0000000... D fileX\r
+:000000 100644 0000000... 0123456... A file0</literallayout>\r
+<simpara>and the contents of the deleted file fileX is similar enough to\r
+the contents of the created file file0, then rename detection\r
+merges these filepairs and creates:</simpara>\r
+<literallayout>:100644 100644 0123456... 0123456... R100 fileX file0</literallayout>\r
+<simpara>When the "-C" option is used, the original contents of modified files,\r
+and deleted files (and also unmodified files, if the\r
+"--find-copies-harder" option is used) are considered as candidates\r
+of the source files in rename/copy operation. If the input were like\r
+these filepairs, that talk about a modified file fileY and a newly\r
+created file file0:</simpara>\r
+<literallayout>:100644 100644 0123456... 1234567... M fileY\r
+:000000 100644 0000000... bcd3456... A file0</literallayout>\r
+<simpara>the original contents of fileY and the resulting contents of\r
+file0 are compared, and if they are similar enough, they are\r
+changed to:</simpara>\r
+<literallayout>:100644 100644 0123456... 1234567... M fileY\r
+:100644 100644 0123456... bcd3456... C100 fileY file0</literallayout>\r
+<simpara>In both rename and copy detection, the same "extent of changes"\r
+algorithm used in diffcore-break is used to determine if two\r
+files are "similar enough", and can be customized to use\r
+a similarity score different from the default of 50% by giving a\r
+number after the "-M" or "-C" option (e.g. "-M8" to tell it to use\r
+8/10 = 80%).</simpara>\r
+<simpara>Note. When the "-C" option is used with <literal>--find-copies-harder</literal>\r
+option, <emphasis>git-diff-*</emphasis> commands feed unmodified filepairs to\r
+diffcore mechanism as well as modified ones. This lets the copy\r
+detector consider unmodified files as copy source candidates at\r
+the expense of making it slower. Without <literal>--find-copies-harder</literal>,\r
+<emphasis>git-diff-*</emphasis> commands can detect copies only if the file that was\r
+copied happened to have been modified in the same changeset.</simpara>\r
+</simplesect>\r
+<simplesect id="_diffcore_merge_broken_for_putting_complete_rewrites_back_together">\r
+<title>diffcore-merge-broken: For Putting "Complete Rewrites" Back Together</title>\r
+<simpara>This transformation is used to merge filepairs broken by\r
+diffcore-break, and not transformed into rename/copy by\r
+diffcore-rename, back into a single modification. This always\r
+runs when diffcore-break is used.</simpara>\r
+<simpara>For the purpose of merging broken filepairs back, it uses a\r
+different "extent of changes" computation from the ones used by\r
+diffcore-break and diffcore-rename. It counts only the deletion\r
+from the original, and does not count insertion. If you removed\r
+only 10 lines from a 100-line document, even if you added 910\r
+new lines to make a new 1000-line document, you did not do a\r
+complete rewrite. diffcore-break breaks such a case in order to\r
+help diffcore-rename to consider such filepairs as candidate of\r
+rename/copy detection, but if filepairs broken that way were not\r
+matched with other filepairs to create rename/copy, then this\r
+transformation merges them back into the original\r
+"modification".</simpara>\r
+<simpara>The "extent of changes" parameter can be tweaked from the\r
+default 80% (that is, unless more than 80% of the original\r
+material is deleted, the broken pairs are merged back into a\r
+single modification) by giving a second number to -B option,\r
+like these:</simpara>\r
+<itemizedlist>\r
+<listitem>\r
+<simpara>\r
+-B50/60 (give 50% "break score" to diffcore-break, use 60%\r
+ for diffcore-merge-broken).\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+-B/60 (the same as above, since diffcore-break defaults to 50%).\r
+</simpara>\r
+</listitem>\r
+</itemizedlist>\r
+<simpara>Note that earlier implementation left a broken pair as a separate\r
+creation and deletion patches. This was an unnecessary hack and\r
+the latest implementation always merges all the broken pairs\r
+back into modifications, but the resulting patch output is\r
+formatted differently for easier review in case of such\r
+a complete rewrite by showing the entire contents of old version\r
+prefixed with <emphasis>-</emphasis>, followed by the entire contents of new\r
+version prefixed with <emphasis>+</emphasis>.</simpara>\r
+</simplesect>\r
+<simplesect id="_diffcore_pickaxe_for_detecting_addition_deletion_of_specified_string">\r
+<title>diffcore-pickaxe: For Detecting Addition/Deletion of Specified String</title>\r
+<simpara>This transformation is used to find filepairs that represent\r
+changes that touch a specified string, and is controlled by the\r
+-S option and the <literal>--pickaxe-all</literal> option to the <emphasis>git-diff-*</emphasis>\r
+commands.</simpara>\r
+<simpara>When diffcore-pickaxe is in use, it checks if there are\r
+filepairs whose "original" side has the specified string and\r
+whose "result" side does not. Such a filepair represents "the\r
+string appeared in this changeset". It also checks for the\r
+opposite case that loses the specified string.</simpara>\r
+<simpara>When <literal>--pickaxe-all</literal> is not in effect, diffcore-pickaxe leaves\r
+only such filepairs that touch the specified string in its\r
+output. When <literal>--pickaxe-all</literal> is used, diffcore-pickaxe leaves all\r
+filepairs intact if there is such a filepair, or makes the\r
+output empty otherwise. The latter behaviour is designed to\r
+make reviewing of the changes in the context of the whole\r
+changeset easier.</simpara>\r
+</simplesect>\r
+<simplesect id="_diffcore_order_for_sorting_the_output_based_on_filenames">\r
+<title>diffcore-order: For Sorting the Output Based on Filenames</title>\r
+<simpara>This is used to reorder the filepairs according to the user’s\r
+(or project’s) taste, and is controlled by the -O option to the\r
+<emphasis>git-diff-*</emphasis> commands.</simpara>\r
+<simpara>This takes a text file each of whose lines is a shell glob\r
+pattern. Filepairs that match a glob pattern on an earlier line\r
+in the file are output before ones that match a later line, and\r
+filepairs that do not match any glob pattern are output last.</simpara>\r
+<simpara>As an example, a typical orderfile for the core git probably\r
+would look like this:</simpara>\r
+<literallayout>README\r
+Makefile\r
+Documentation\r
+*.h\r
+*.c\r
+t</literallayout>\r
+</simplesect>\r
+<simplesect id="_see_also">\r
+<title>SEE ALSO</title>\r
+<simpara><xref linkend="git-diff(1)"/>,\r
+<xref linkend="git-diff-files(1)"/>,\r
+<xref linkend="git-diff-index(1)"/>,\r
+<xref linkend="git-diff-tree(1)"/>,\r
+<xref linkend="git-format-patch(1)"/>,\r
+<xref linkend="git-log(1)"/>,\r
+<xref linkend="gitglossary(7)"/>,\r
+<ulink url="user-manual.html">The Git User’s Manual</ulink></simpara>\r
+</simplesect>\r
+<simplesect id="_git">\r
+<title>GIT</title>\r
+<simpara>Part of the <xref linkend="git(1)"/> suite.</simpara>\r
+</simplesect>\r
+</article>\r
OSDN Git Service
