{"thread":{"id":"2264","subject":"[PATCH] Minor clarifications in diffcore documentation","startedAt":"2005-10-29T04:15:49Z","lastAt":"2005-10-29T16:49:57Z","messageCount":3,"participants":["c.shoemaker@cox.net","Junio C Hamano","Chris Shoemaker"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"10778","messageId":"E1EVi8D-0002TT-Ik@localhost","threadId":"2264","inReplyTo":null,"subject":"[PATCH] Minor clarifications in diffcore documentation","fromName":"","fromEmail":"c.shoemaker@cox.net","sentAt":"2005-10-29T04:15:49Z","receivedAt":"2005-10-29T04:15:49Z","isPatch":true,"sender":{"key":"c.shoemaker@cox.net","avatar":null},"body":"Signed-off-by: Chris Shoemaker <c.shoemaker at cox.net>\n\n---\n\n Documentation/diffcore.txt |   65 ++++++++++++++++++++++++++------------------\n 1 files changed, 38 insertions(+), 27 deletions(-)\n\n805e13719e93be23d3e24e182d45056fab192a25\ndiff --git a/Documentation/diffcore.txt b/Documentation/diffcore.txt\n--- a/Documentation/diffcore.txt\n+++ b/Documentation/diffcore.txt\n@@ -6,13 +6,12 @@ June 2005\n Introduction\n ------------\n \n-The diff commands git-diff-index, git-diff-files, and\n-git-diff-tree can be told to manipulate differences they find\n-in unconventional ways before showing diff(1) output.  The\n-manipulation is collectively called \"diffcore transformation\".\n-This short note describes what they are and how to use them to\n-produce diff outputs that are easier to understand than the\n-conventional kind.\n+The diff commands git-diff-index, git-diff-files, git-diff-tree, and\n+git-diff-stages can be told to manipulate differences they find in\n+unconventional ways before showing diff(1) output.  The manipulation\n+is collectively called \"diffcore transformation\".  This short note\n+describes what they are and how to use them to produce diff outputs\n+that are easier to understand than the conventional kind.\n \n \n The chain of operation\n@@ -29,7 +28,10 @@ files:\n  - git-diff-files compares contents of the index file and the\n    working directory;\n \n- - git-diff-tree compares contents of two \"tree\" objects.\n+ - git-diff-tree compares contents of two \"tree\" objects;\n+\n+ - git-diff-stages compares contents of blobs at two stages in an\n+   unmerged index file.\n \n In all of these cases, the commands themselves compare\n corresponding paths in the two sets of files.  The result of\n@@ -65,14 +67,23 @@ format sections of the manual for git-di\n diff-patch format.\n \n \n-diffcore-pathspec\n+diffcore-pathspec: For Ignoring Files Outside Our Consideration\n -----------------\n \n The first transformation in the chain is diffcore-pathspec, and\n is controlled by giving the pathname parameters to the\n git-diff-* commands on the command line.  The pathspec is used\n to limit the world diff operates in.  It removes the filepairs\n-outside the specified set of pathnames.\n+outside the specified set of pathnames.  E.g. If the input set \n+of filepairs included:\n+\n+------------------------------------------------\n+:100644 100644 bcd1234... 0123456... M junkfile\n+------------------------------------------------\n+\n+but the command invocation was \"git-diff-files myfile\", then the\n+junkfile entry would be removed from the list because only \"myfile\"\n+is under consideration.\n \n Implementation note.  For performance reasons, git-diff-tree\n uses the pathname parameters on the command line to cull set of\n@@ -80,7 +91,7 @@ filepairs it feeds the diffcore mechanis\n use diffcore-pathspec, but the end result is the same.\n \n \n-diffcore-break\n+diffcore-break: For Splitting Up \"Complete Rewrites\"\n --------------\n \n The second transformation in the chain is diffcore-break, and is\n@@ -115,7 +126,7 @@ the original is used), and can be custom\n after \"-B\" option (e.g. \"-B75\" to tell it to use 75%).\n \n \n-diffcore-rename\n+diffcore-rename: For Detection Renames and Copies\n ---------------\n \n This transformation is used to detect renames and copies, and is\n@@ -136,16 +147,16 @@ merges these filepairs and creates:\n :100644 100644 0123456... 0123456... R100 fileX file0\n ------------------------------------------------\n \n-When the \"-C\" option is used, the original contents of modified\n-files and contents of unchanged files are considered as\n-candidates of the source files in rename/copy operation, in\n-addition to the deleted files.  If the input were like these\n-filepairs, that talk about a modified file fileY and a newly\n+When the \"-C\" option is used, the original contents of modified files,\n+and deleted files (and also unmodified files, if the\n+\"\\--find-copies-harder\" option is used) are considered as candidates\n+of the source files in rename/copy operation.  If the input were like\n+these filepairs, that talk about a modified file fileY and a newly\n created file file0:\n \n ------------------------------------------------\n :100644 100644 0123456... 1234567... M fileY\n-:000000 100644 0000000... 0123456... A file0\n+:000000 100644 0000000... bcd3456... A file0\n ------------------------------------------------\n \n the original contents of fileY and the resulting contents of\n@@ -154,14 +165,14 @@ changed to:\n \n ------------------------------------------------\n :100644 100644 0123456... 1234567... M fileY\n-:100644 100644 0123456... 0123456... C100 fileY file0\n+:100644 100644 0123456... bcd3456... C100 fileY file0\n ------------------------------------------------\n \n In both rename and copy detection, the same \"extent of changes\"\n algorithm used in diffcore-break is used to determine if two\n files are \"similar enough\", and can be customized to use\n-similarity score different from the default 50% by giving a\n-number after \"-M\" or \"-C\" option (e.g. \"-M8\" to tell it to use\n+a similarity score different from the default of 50% by giving a\n+number after the \"-M\" or \"-C\" option (e.g. \"-M8\" to tell it to use\n 8/10 = 80%).\n \n Note.  When the \"-C\" option is used with `\\--find-copies-harder`\n@@ -173,7 +184,7 @@ git-diff-\\* commands can detect copies o\n copied happened to have been modified in the same changeset.\n \n \n-diffcore-merge-broken\n+diffcore-merge-broken: For Putting \"Complete Rewrites\" Back Together\n ---------------------\n \n This transformation is used to merge filepairs broken by\n@@ -215,7 +226,7 @@ prefixed with '-', followed by the entir\n version prefixed with '+'.\n \n \n-diffcore-pickaxe\n+diffcore-pickaxe: For Detecting Addition/Deletion of Specified String\n ----------------\n \n This transformation is used to find filepairs that represent\n@@ -230,7 +241,7 @@ string appeared in this changeset\".  It \n opposite case that loses the specified string.\n \n When `\\--pickaxe-all` is not in effect, diffcore-pickaxe leaves\n-only such filepairs that touches the specified string in its\n+only such filepairs that touch the specified string in its\n output.  When `\\--pickaxe-all` is used, diffcore-pickaxe leaves all\n filepairs intact if there is such a filepair, or makes the\n output empty otherwise.  The latter behaviour is designed to\n@@ -238,19 +249,19 @@ make reviewing of the changes in the con\n changeset easier.\n \n \n-diffcore-order\n+diffcore-order: For Sorting the Output Based on Filenames\n --------------\n \n This is used to reorder the filepairs according to the user's\n (or project's) taste, and is controlled by the -O option to the\n git-diff-* commands.\n \n-This takes a text file each of whose line is a shell glob\n+This takes a text file each of whose lines is a shell glob\n pattern.  Filepairs that match a glob pattern on an earlier line\n in the file are output before ones that match a later line, and\n filepairs that do not match any glob pattern are output last.\n \n-As an example, typical orderfile for the core git probably\n+As an example, a typical orderfile for the core git probably\n would look like this:\n \n ------------------------------------------------\n"},{"id":"10787","messageId":"7v64rg3nuq.fsf@assigned-by-dhcp.cox.net","threadId":"2264","inReplyTo":"E1EVi8D-0002TT-Ik@localhost","subject":"Re: [PATCH] Minor clarifications in diffcore documentation","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-10-29T05:15:41Z","receivedAt":"2005-10-29T05:15:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"c.shoemaker@cox.net writes:\n\n>  ------------------------------------------------\n>  :100644 100644 0123456... 1234567... M fileY\n> -:000000 100644 0000000... 0123456... A file0\n> +:000000 100644 0000000... bcd3456... A file0\n>  ------------------------------------------------\n>  \n>  the original contents of fileY and the resulting contents of\n> @@ -154,14 +165,14 @@ changed to:\n>  \n>  ------------------------------------------------\n>  :100644 100644 0123456... 1234567... M fileY\n> -:100644 100644 0123456... 0123456... C100 fileY file0\n> +:100644 100644 0123456... bcd3456... C100 fileY file0\n>  ------------------------------------------------\n\n\nI think with this change you wanted to say that a copy does not\nhave to be a literal copy but a copy-edit.  But if that is the\ncase, I suspect that the similarity index would be slightly less\nthan 100.\n\nIf I misunderstood the reason of this change please let me know.\n\nAll patches, including this one, look fine to me.  Thanks.\n"},{"id":"10792","messageId":"20051029164957.GA20990@pe.Belkin","threadId":"2264","inReplyTo":"7v64rg3nuq.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Minor clarifications in diffcore documentation","fromName":"Chris Shoemaker","fromEmail":"c.shoemaker@cox.net","sentAt":"2005-10-29T16:49:57Z","receivedAt":"2005-10-29T16:49:57Z","isPatch":true,"sender":{"key":"c.shoemaker@cox.net","avatar":null},"body":"On Fri, Oct 28, 2005 at 10:15:41PM -0700, Junio C Hamano wrote:\n> I think with this change you wanted to say that a copy does not\n> have to be a literal copy but a copy-edit.  But if that is the\n> case, I suspect that the similarity index would be slightly less\n> than 100.\n\nIndeed.\n\n-chris\n"}]}