freshlybakedca.ke
Git fork
1gitdiffcore(7)
2==============
3
4NAME
5----
6gitdiffcore - Tweaking diff output
7
8SYNOPSIS
9--------
10[verse]
11'git diff' *
12
13DESCRIPTION
14-----------
15
16The diff commands 'git diff-index', 'git diff-files', and 'git diff-tree'
17can be told to manipulate differences they find in
18unconventional ways before showing 'diff' output. The manipulation
19is collectively called "diffcore transformation". This short note
20describes what they are and how to use them to produce 'diff' output
21that is easier to understand than the conventional kind.
22
23
24The chain of operation
25----------------------
26
27The 'git diff-{asterisk}' family works by first comparing two sets of
28files:
29
30 - 'git diff-index' compares contents of a "tree" object and the
31 working directory (when `--cached` flag is not used) or a
32 "tree" object and the index file (when `--cached` flag is
33 used);
34
35 - 'git diff-files' compares contents of the index file and the
36 working directory;
37
38 - 'git diff-tree' compares contents of two "tree" objects;
39
40In all of these cases, the commands themselves first optionally limit
41the two sets of files by any pathspecs given on their command-lines,
42and compare corresponding paths in the two resulting sets of files.
43
44The pathspecs are used to limit the world diff operates in. They remove
45the filepairs outside the specified sets of pathnames. E.g. If the
46input set of filepairs included:
47
48------------------------------------------------
49:100644 100644 bcd1234... 0123456... M junkfile
50------------------------------------------------
51
52but the command invocation was `git diff-files myfile`, then the
53junkfile entry would be removed from the list because only "myfile"
54is under consideration.
55
56The result of comparison is passed from these commands to what is
57internally called "diffcore", in a format similar to what is output
58when the -p option is not used. E.g.
59
60------------------------------------------------
61in-place edit :100644 100644 bcd1234... 0123456... M file0
62create :000000 100644 0000000... 1234567... A file4
63delete :100644 000000 1234567... 0000000... D file5
64unmerged :000000 000000 0000000... 0000000... U file6
65------------------------------------------------
66
67The diffcore mechanism is fed a list of such comparison results
68(each of which is called "filepair", although at this point each
69of them talks about a single file), and transforms such a list
70into another list. There are currently 5 such transformations:
71
72- diffcore-break
73- diffcore-rename
74- diffcore-merge-broken
75- diffcore-pickaxe
76- diffcore-order
77- diffcore-rotate
78
79These are applied in sequence. The set of filepairs 'git diff-{asterisk}'
80commands find are used as the input to diffcore-break, and
81the output from diffcore-break is used as the input to the
82next transformation. The final result is then passed to the
83output routine and generates either diff-raw format (see Output
84format sections of the manual for 'git diff-{asterisk}' commands) or
85diff-patch format.
86
87
88diffcore-break: For Splitting Up Complete Rewrites
89--------------------------------------------------
90
91The second transformation in the chain is diffcore-break, and is
92controlled by the -B option to the 'git diff-{asterisk}' commands. This is
93used to detect a filepair that represents "complete rewrite" and
94break such filepair into two filepairs that represent delete and
95create. E.g. If the input contained this filepair:
96
97------------------------------------------------
98:100644 100644 bcd1234... 0123456... M file0
99------------------------------------------------
100
101and if it detects that the file "file0" is completely rewritten,
102it changes it to:
103
104------------------------------------------------
105:100644 000000 bcd1234... 0000000... D file0
106:000000 100644 0000000... 0123456... A file0
107------------------------------------------------
108
109For the purpose of breaking a filepair, diffcore-break examines
110the extent of changes between the contents of the files before
111and after modification (i.e. the contents that have "bcd1234..."
112and "0123456..." as their SHA-1 content ID, in the above
113example). The amount of deletion of original contents and
114insertion of new material are added together, and if it exceeds
115the "break score", the filepair is broken into two. The break
116score defaults to 50% of the size of the smaller of the original
117and the result (i.e. if the edit shrinks the file, the size of
118the result is used; if the edit lengthens the file, the size of
119the original is used), and can be customized by giving a number
120after "-B" option (e.g. "-B75" to tell it to use 75%).
121
122
123diffcore-rename: For Detecting Renames and Copies
124-------------------------------------------------
125
126This transformation is used to detect renames and copies, and is
127controlled by the -M option (to detect renames) and the -C option
128(to detect copies as well) to the 'git diff-{asterisk}' commands. If the
129input contained these filepairs:
130
131------------------------------------------------
132:100644 000000 0123456... 0000000... D fileX
133:000000 100644 0000000... 0123456... A file0
134------------------------------------------------
135
136and the contents of the deleted file fileX is similar enough to
137the contents of the created file file0, then rename detection
138merges these filepairs and creates:
139
140------------------------------------------------
141:100644 100644 0123456... 0123456... R100 fileX file0
142------------------------------------------------
143
144When the "-C" option is used, the original contents of modified files,
145and deleted files (and also unmodified files, if the
146"--find-copies-harder" option is used) are considered as candidates
147of the source files in rename/copy operation. If the input were like
148these filepairs, that talk about a modified file fileY and a newly
149created file file0:
150
151------------------------------------------------
152:100644 100644 0123456... 1234567... M fileY
153:000000 100644 0000000... bcd3456... A file0
154------------------------------------------------
155
156the original contents of fileY and the resulting contents of
157file0 are compared, and if they are similar enough, they are
158changed to:
159
160------------------------------------------------
161:100644 100644 0123456... 1234567... M fileY
162:100644 100644 0123456... bcd3456... C100 fileY file0
163------------------------------------------------
164
165In both rename and copy detection, the same "extent of changes"
166algorithm used in diffcore-break is used to determine if two
167files are "similar enough", and can be customized to use
168a similarity score different from the default of 50% by giving a
169number after the "-M" or "-C" option (e.g. "-M8" to tell it to use
1708/10 = 80%).
171
172Note that when rename detection is on but both copy and break
173detection are off, rename detection adds a preliminary step that first
174checks if files are moved across directories while keeping their
175filename the same. If there is a file added to a directory whose
176contents are sufficiently similar to a file with the same name that got
177deleted from a different directory, it will mark them as renames and
178exclude them from the later quadratic step (the one that pairwise
179compares all unmatched files to find the "best" matches, determined by
180the highest content similarity). So, for example, if a deleted
181docs/ext.txt and an added docs/config/ext.txt are similar enough, they
182will be marked as a rename and prevent an added docs/ext.md that may
183be even more similar to the deleted docs/ext.txt from being considered
184as the rename destination in the later step. For this reason, the
185preliminary "match same filename" step uses a bit higher threshold to
186mark a file pair as a rename and stop considering other candidates for
187better matches. At most, one comparison is done per file in this
188preliminary pass; so if there are several remaining ext.txt files
189throughout the directory hierarchy after exact rename detection, this
190preliminary step may be skipped for those files.
191
192Note. When the "-C" option is used with `--find-copies-harder`
193option, 'git diff-{asterisk}' commands feed unmodified filepairs to
194diffcore mechanism as well as modified ones. This lets the copy
195detector consider unmodified files as copy source candidates at
196the expense of making it slower. Without `--find-copies-harder`,
197'git diff-{asterisk}' commands can detect copies only if the file that was
198copied happened to have been modified in the same changeset.
199
200
201diffcore-merge-broken: For Putting Complete Rewrites Back Together
202------------------------------------------------------------------
203
204This transformation is used to merge filepairs broken by
205diffcore-break, and not transformed into rename/copy by
206diffcore-rename, back into a single modification. This always
207runs when diffcore-break is used.
208
209For the purpose of merging broken filepairs back, it uses a
210different "extent of changes" computation from the ones used by
211diffcore-break and diffcore-rename. It counts only the deletion
212from the original, and does not count insertion. If you removed
213only 10 lines from a 100-line document, even if you added 910
214new lines to make a new 1000-line document, you did not do a
215complete rewrite. diffcore-break breaks such a case in order to
216help diffcore-rename to consider such filepairs as a candidate of
217rename/copy detection, but if filepairs broken that way were not
218matched with other filepairs to create rename/copy, then this
219transformation merges them back into the original
220"modification".
221
222The "extent of changes" parameter can be tweaked from the
223default 80% (that is, unless more than 80% of the original
224material is deleted, the broken pairs are merged back into a
225single modification) by giving a second number to -B option,
226like these:
227
228* -B50/60 (give 50% "break score" to diffcore-break, use 60%
229 for diffcore-merge-broken).
230
231* -B/60 (the same as above, since diffcore-break defaults to 50%).
232
233Note that earlier implementation left a broken pair as separate
234creation and deletion patches. This was an unnecessary hack, and
235the latest implementation always merges all the broken pairs
236back into modifications, but the resulting patch output is
237formatted differently for easier review in case of such
238a complete rewrite by showing the entire contents of the old version
239prefixed with '-', followed by the entire contents of the new
240version prefixed with '+'.
241
242
243diffcore-pickaxe: For Detecting Addition/Deletion of Specified String
244---------------------------------------------------------------------
245
246This transformation limits the set of filepairs to those that change
247specified strings between the preimage and the postimage in a certain
248way. -S<block-of-text> and -G<regular-expression> options are used to
249specify different ways these strings are sought.
250
251"-S<block-of-text>" detects filepairs whose preimage and postimage
252have different number of occurrences of the specified block of text.
253By definition, it will not detect in-file moves. Also, when a
254changeset moves a file wholesale without affecting the interesting
255string, diffcore-rename kicks in as usual, and `-S` omits the filepair
256(since the number of occurrences of that string didn't change in that
257rename-detected filepair). When used with `--pickaxe-regex`, treat
258the <block-of-text> as an extended POSIX regular expression to match,
259instead of a literal string.
260
261"-G<regular-expression>" (mnemonic: grep) detects filepairs whose
262textual diff has an added or a deleted line that matches the given
263regular expression. This means that it will detect in-file (or what
264rename-detection considers the same file) moves, which is noise. The
265implementation runs diff twice and greps, and this can be quite
266expensive. To speed things up, binary files without textconv filters
267will be ignored.
268
269When `-S` or `-G` are used without `--pickaxe-all`, only filepairs
270that match their respective criterion are kept in the output. When
271`--pickaxe-all` is used, if even one filepair matches their respective
272criterion in a changeset, the entire changeset is kept. This behavior
273is designed to make reviewing changes in the context of the whole
274changeset easier.
275
276diffcore-order: For Sorting the Output Based on Filenames
277---------------------------------------------------------
278
279This is used to reorder the filepairs according to the user's
280(or project's) taste, and is controlled by the -O option to the
281'git diff-{asterisk}' commands.
282
283This takes a text file each of whose lines is a shell glob
284pattern. Filepairs that match a glob pattern on an earlier line
285in the file are output before ones that match a later line, and
286filepairs that do not match any glob pattern are output last.
287
288As an example, a typical orderfile for the core Git probably
289would look like this:
290
291------------------------------------------------
292README
293Makefile
294Documentation
295*.h
296*.c
297t
298------------------------------------------------
299
300diffcore-rotate: For Changing At Which Path Output Starts
301---------------------------------------------------------
302
303This transformation takes one pathname, and rotates the set of
304filepairs so that the filepair for the given pathname comes first,
305optionally discarding the paths that come before it. This is used
306to implement the `--skip-to` and the `--rotate-to` options. It is
307an error when the specified pathname is not in the set of filepairs,
308but it is not useful to error out when used with "git log" family of
309commands, because it is unreasonable to expect that a given path
310would be modified by each and every commit shown by the "git log"
311command. For this reason, when used with "git log", the filepair
312that sorts the same as, or the first one that sorts after, the given
313pathname is where the output starts.
314
315Use of this transformation combined with diffcore-order will produce
316unexpected results, as the input to this transformation is likely
317not sorted when diffcore-order is in effect.
318
319
320SEE ALSO
321--------
322linkgit:git-diff[1],
323linkgit:git-diff-files[1],
324linkgit:git-diff-index[1],
325linkgit:git-diff-tree[1],
326linkgit:git-format-patch[1],
327linkgit:git-log[1],
328linkgit:gitglossary[7],
329link:user-manual.html[The Git User's Manual]
330
331GIT
332---
333Part of the linkgit:git[1] suite