1App::ccdiff(3) User Contributed Perl Documentation App::ccdiff(3)
2
6 ccdiff - Colored Character diff
7
9 ccdiff [options] file1|- file2|-
10 ccdiff [options] dir1 dir2
11 ccdiff --help
13 ccdiff --man
14 ccdiff --info
15
17 Show the diff between two files on a character by character base. In
18 contrast to the standard diff tools, this tool uses the diff algorithm
19 horizontally for each line in the vertical diff, highlighting the
20 changes. This is very handy in hard to spot changes like "O" to 0, "I"
21 to "l" or 1 and whitespace.
22 If there are two argument, and both are a folder/directory, a recursive
24 diff is executed. This is not available whan used as a (sub)class.
25
27 Command line options
28 --help -?
29 Show a summary of the available command-line options and exit.
30 --version -V
32 Show the version and exit.
33 --man
35 Show this manual using pod2man and nroff.
36 --info
38 Show this manual using pod2text.
39 --utf-8 -U
41 All I/O (streams to compare and standard out) are in UTF-8.
42 --diff-class=C --dc=C
44 Select the class used to execute the diff. By default "ccdiff" will
45 select the first available out of "Algorithm::Diff::XS" or
46 "Algorithm::Diff".
47 Sometime the "XS" version fails on encoding and the pure-perl version
49 will work just fine. You can force "ccdiff" to use either
50 Select the pure-perl version with any of "PP", "AD",
52 "Algorthm::Diff", "Algorithm-Diff", or "Algorithm::Diff::PP" (case
53 insensitive)
54 --dc=pp
56 --dc=algorithm-diff
57 --diff-class=Algorithm::Diff::PP
58 Select the XS version with any of "XS", "ADX", "Algorthm::Diff::XS",
60 or "Algorithm-Diff-XS" (case insensitive)
61 --dc=xs
63 --dc=algorithm-diff-xs
64 --diff-class=Algorithm::Diff::XS
65 --unified[=3] -u [3]
67 Generate a unified diff. The number of context lines is optional.
68 When omitted it defaults to 3. Currently there is no provision of
69 dealing with overlapping diff chunks. If the common part between two
70 diff chunks is shorter than twice the number of context lines, some
71 lines may show twice.
72 The default is to use traditional diff:
74 5,5c5,5
76 < Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
77 ---
78 > Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
79 a unified diff (-u1) would be
81 5,5c5,5
83 Tue Sep 6 05:43:59 2005,B.O.Q.S.,,1125978239,1943341
84 -Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
85 +Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
86 Mon Feb 23 10:37:02 2004,R.X.K.S.,van,1077529022,1654127
87 --verbose[=1] -v[1]
89 Show an additional line for each old or new section in a change chunk
90 (not for added or deleted lines) that shows the hexadecimal value of
91 each character. If "--utf-8" is in effect, it will show the Unicode
92 character name(s).
93 This is a debugging option, so invisible characters can still be
95 "seen".
96 "--verbose" accepts an optional verbosity-level. On level 2 and up,
98 all horizontal changes get left-and-right markers inserted to enable
99 seeing the location of the ZERO WIDTH or invisible characters. With
100 level 3 and up and Unicode enabled, the changed characters will also
101 show the codepoint in hex.
102 An example of this:
104 With -Uu0v0:
106 1,1c1,1
108 - A BCDE Fg
109 + A BcdEFg
110 With -Uu0v1:
112 1,1c1,1
114 - A BCDE Fg
115 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
116 + A BcdEFg
117 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
118 With -Uu0v2:
120 1,1c1,1
122 - A ↱ ↰B↱CD↰E↱ ↰Fg
123 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
124 + A B↱cd↰E↱↰Fg
125 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
126 With -Uu0v3:
128 1,1c1,1
130 - A ↱ ↰B↱CD↰E↱ ↰Fg
131 - -- verbose : SPACE (U+000020), LATIN CAPITAL LETTER C (U+000043), LATIN CAPITAL LETTER D (U+000044), SPACE (U+000020)
132 + A B↱cd↰E↱↰Fg
133 + -- verbose : LATIN SMALL LETTER C (U+000063), LATIN SMALL LETTER D (U+000064), ZERO WIDTH SPACE (U+00200B)
134 With -Uu0v2 --ascii:
136 1,1c1,1
138 - A > <B>CD<E> <Fg
139 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
140 + A B>cd<E><Fg
141 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
142 the word "verbose" and the character markers will be displayed using
144 the "verbose" color. The characters used for the markers can be
145 defined in your configuration file as "chr_cml" (the character used
146 as marker on the left) and "chr_cmr" (the character used as marker on
147 the right).
148 --markers -m
150 Use markers under each changed character in change-chunks.
151 "--markers" is especially useful if the terminal does not support
153 colors, or if you want to copy/paste the output to (ASCII) mail. See
154 also "--ascii". The markers will have the same color as added or
155 deleted text.
156 This will look like (with unified diff):
158 5,5c5,5
160 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
161 - ▼ ▼
162 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
163 + ▲ ▲
164 The characters used for the markers can be defined in your
166 configuration file as "chr_old" (the character used as marker under
167 removed characters) and "chr_new" (the character used as marker under
168 added characters).
169 If "--ellipsis" is also in effect and either the "chr_eli" is longer
171 than one character or "--verbose" level is over 2, this option is
172 automatically disabled.
173 --ascii -a
175 Use (colored) ASCII indicators instead of Unicode. The default
176 indicators are Unicode characters that stand out better. The markers
177 will have the same color as added or deleted text.
178 For the vertical markers ("-m") that would look like:
180 5,5c5,5
182 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
183 - ^ ^
184 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
185 + ^ ^
186 For the positional indicators, I did consider using U+034e (COMBINING
188 UPWARDS ARROW BELOW), but as most terminals are probably unable to
189 show it due to line height changes, I did not pursue the idea.
190 --pink -p
192 Change the default "red" for deleted text to the color closest to
193 pink that is supported by Term::ANSIColor: "magenta".
194 --reverse -r
196 Reverse/invert the foreground and background for the colored
197 indicators.
198 If the foreground color has "bold", it will be stripped from the new
200 background color.
201 --swap -s
203 Swap the colors for new and old.
204 --list-colors
206 List available colors and exit.
207 --no-colors
209 Disable all colors. Useful for redirecting the diff output to a file
210 that is to be included in documentation.
211 This is the default if the environment variable $NO_COLOR has a true
213 value or if the environment variable $CLICOLOR is set to a false
214 value. If set, $CLICOLOR_FORCE will overrule the default of
215 $NO_COLOR.
216 --old=color
218 Define the foreground color for deleted text.
219 --new=color
221 Define the foreground color for added text.
222 --bg=color
224 Define the background color for changed text.
225 --index --idx -I
227 Prefix position indicators with an index.
228 [001] 5,5c5,5
230 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
231 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
232 If a positive number is passed ("--index=4" or "-I 4"), display just
234 the chunk with that index, using the "verbose" color:
235 This is useful in combination with "--verbose".
237 --threshold=2 -t 2
239 Defines the number of lines a change block may differ before the
240 fall-back of horizontal diff to vertical diff.
241 If a chunk describes a change, and the number of lines in the
243 original block has fewer or more lines than the new block and that
244 difference exceeds this threshold, "ccdiff" will fall-back to
245 vertical diff.
246 --heuristics=n -h n
248 Defines the percentage of character-changes a change block may differ
249 before the fall-back of horizontal diff to vertical diff.
250 This percentage is calculated as "(characters removed + characters
252 added) / (2 * characters unchanged))".
253 --ellipsis=n -e n
255 Defines the number of characters to keep on each side of a
256 horizontal-equal segment. The default is 0, meaning do not compress.
257 If set to a positive number, and the length of a segment of equal
259 characters inside a horizontal diff is longer than twice this value,
260 the middle part is replaced with "┈ U02508 \N{BOX DRAWINGS LIGHT
261 QUADRUPLE DASH HORIZONTAL}" (instead of … U02026, as HORIZONTAL
262 ELLIPSIS does not stand out enough).
263 With "-u0me3" that would be like
265 5,5c5,5
267 -Sat┈07:08:33┈ 1998,I.┈539
268 - ▼ ▼
269 +Sat┈07:00:33┈ 1993,I.┈539
270 + ▲ ▲
271 With "-u0e3 -v2" like
273 5,5c5,5
275 -Sat↤9↦07:0↱0↰:33 199↱3↰,I.↤23↦539
276 - -- verbose : DIGIT ZERO, DIGIT THREE
277 +Sat↤9↦07:0↱8↰:33 199↱8↰,I.↤23↦539
278 + -- verbose : DIGIT EIGHT, DIGIT EIGHT
279 The text used for the replaced text can be defined in your
281 configuration file as "chr_eli" and/or "chr_eli_v".
282 --ignore-case -i
284 Ignore case on comparison.
285 --ignore-all-space -w
287 Ignore all white-space changes. This will set all options "-b", "-Z",
288 "-E", and "-B".
289 --ignore-trailing-space -Z
291 Ignore changes in trailing white-space (tabs and spaces).
292 --ignore-ws|ignore-space-change -b
294 Ignore changes in horizontal white-space (tabs and spaces). This does
295 not include white-space changes that split non-white-space or remove
296 white-space between two non-white-space elements.
297 --ignore-tab-expansion -E
299 NYI
300 --ignore-blank-lines -B
302 Just Partly Implemented (WIP)
303 Configuration files
305 In order to be able to overrule the defaults set in "ccdiff", one can
306 set options specific for this login. The following option files are
307 looked for in this order:
308 - $HOME/ccdiff.rc
310 - $HOME/.ccdiffrc
311 - $HOME/.config/ccdiff
312 and evaluated in that order. Any options specified in a file later in
314 that chain will overwrite previously set options.
315 Option files are only read and evaluated if they are not empty and not
317 writable by others than the owner.
318 The syntax of the file is one option per line, where leading and
320 trailing white-space is ignored. If that line then starts with one of
321 the options listed below, followed by optional white-space followed by
322 either an "=" or a ":", followed by optional white-space and the
323 values, the value is assigned to the option. The values "no" and
324 "false" (case insensitive) are aliases for 0. The values "yes" and
325 "true" are aliases to -1 (-1 being a true value).
326 Between parens is the corresponding command-line option.
328 unified (-u)
330 If you prefer unified-diff over old-style diff by default, set this
331 to the desired number of context lines:
332 unified : 3
334 The default is undefined
336 markers (-m)
338 markers : false
339 Defines if markers should be used under changed characters. The
341 default is to use colors only. The "-m" command line option will
342 toggle the option when set from a configuration file.
343 ascii (-a)
345 ascii : false
346 Defines to use ASCII markers instead of Unicode markers. The default
348 is to use Unicode markers.
349 reverse (-r)
351 reverse : false
352 Defines if changes are displayed as foreground-color over background-
354 color or background-color over foreground-color. The default is
355 "false", so it will color the changes with the appropriate color
356 ("new" or "old") over the default background color.
357 swap (-s)
359 swap : false
360 Swap the colors for new and old.
362 new (--new)
364 new : green
365 Defines the color to be used for added text. The default is "green".
367 The color "none" is also accepted and disables this color.
369 Any color accepted by Term::ANSIColor is allowed. Any other color
371 will result in a warning. This option can include "bold" either as
372 prefix or as suffix.
373 This option may also be specified as
375 new-color
377 new_color
378 new-colour
379 new_colour
380 old (--old)
382 old : red
383 Defines the color to be used for deleted text. The default is "red".
385 The color "none" is also accepted and disables this color.
387 Any color accepted by Term::ANSIColor is allowed. Any other color
389 will result in a warning. This option can include "bold" either as
390 prefix or as suffix.
391 This option may also be specified as
393 old-color
395 old_color
396 old-colour
397 old_colour
398 bg (--bg)
400 bg : white
401 Defines the color to be used as background for changed text. The
403 default is "white".
404 The color "none" is also accepted and disables this color.
406 Any color accepted by Term::ANSIColor is allowed. Any other color
408 will result in a warning. The "bold" attribute is not allowed.
409 This option may also be specified as
411 bg-color
413 bg_color
414 bg-colour
415 bg_colour
416 background
417 background-color
418 background_color
419 background-colour
420 background_colour
421 header (-H --header --HC=color --header-color=color)
423 header : 1
424 header : blue_on_white
425 Defines if a header is displayed above the diff (default is 1),
427 supported colors are allowed.
428 If the value is a valid supported color, it will show the header in
430 that color scheme. To disable the header set it to 0 in the RC file
431 or use "--no-header" as a command line argument.
432 verbose
434 verbose : cyan
435 Defines the color to be used as color for the verbose tag. The
437 default is "cyan". This color will only be used under "--verbose".
438 The color "none" is also accepted and disables this color.
440 Any color accepted by Term::ANSIColor is allowed. Any other color
442 will result in a warning.
443 This option may also be specified as
445 verbose-color
447 verbose_color
448 verbose-colour
449 verbose_colour
450 utf8 (-U)
452 utf8 : yes
453 Defines whether all I/O is to be interpreted as UTF-8. The default is
455 "no".
456 This option may also be specified as
458 unicode
460 utf
461 utf-8
462 index (-I)
464 index : no
465 Defines if the position indication for a change chunk is prefixed
467 with an index number. The default is "no". The index is 1-based.
468 Without this option, the position indication would be like
470 5,5c5,5
472 19,19d18
473 42a42,42
474 with this option, it would be
476 [001] 5,5c5,5
478 [002] 19,19d18
479 [005] 42a42,42
480 When this option contains a positive integer, "ccdiff" will only show
482 the diff chunk with that index.
483 emacs
485 emacs : no
486 If this option is yes/true, calling "ccdiff" with just one single
488 argument, and that argument being an existing file, the arguments
489 will act as
490 $ ccdiff file~ file
492 if file~ exists.
494 threshold (-t)
496 threshold : 2
497 Defines the number of lines a change block may differ before the
499 fall-back of horizontal diff to vertical diff.
500 heuristics (-h)
502 heuristics : 40
503 Defines the percentage of character-changes a change block may differ
505 before the fall-back of horizontal diff to vertical diff. The default
506 is undefined, meaning no fallback based on heuristics.
507 ellipsis (-e)
509 ellipsis : 0
510 Defines the number of characters to keep on each side of a
512 horizontal-equal segment. The default is 0, meaning to not compress.
513 See also "chr_eli".
514 chr_old
516 chr_old : U+25BC
517 Defines the character used to indicate the position of removed text
519 on the line below the text when option "-m" is in effect.
520 chr_new
522 chr_new : U+25B2
523 Defines the character used to indicate the position of added text on
525 the line below the text when option "-m" is in effect.
526 chr_cml
528 chr_cml : U+21B1
529 Defines the character used to indicate the starting position of
531 changed text in a line when verbose level is 3 and up.
532 chr_cmr
534 chr_cmr : U+21B0
535 Defines the character used to indicate the ending position of changed
537 text in a line when verbose level is 3 and up.
538 chr_eli
540 chr_eli : U+21B0
541 Defines the character used to indicate omitted text in large
543 unchanged text when "--ellipsis"/"-e" is in effect.
544 This character is not equally well visible on all terminals or in all
546 fonts, so you might want to change it to something that stands out
547 better in your environment. Possible suggestions:
548 … U+2026 HORIZONTAL ELLIPSIS
550 ‴ U+2034 TRIPLE PRIME
551 ‷ U+2037 REVERSED TRIPLE PRIME
552 ↔ U+2194 LEFT RIGHT ARROW
553 ↭ U+21ad LEFT RIGHT WAVE ARROW
554 ↮ U+21ae LEFT RIGHT ARROW WITH STROKE
555 ↹ U+21b9 LEFTWARDS ARROW TO BAR OVER RIGHTWARDS ARROW TO BAR
556 ⇄ U+21c4 RIGHTWARDS ARROW OVER LEFTWARDS ARROW
557 ⇆ U+21c6 LEFTWARDS ARROW OVER RIGHTWARDS ARROW
558 ⇎ U+21ce LEFT RIGHT DOUBLE ARROW WITH STROKE
559 ⇔ U+21d4 LEFT RIGHT DOUBLE ARROW
560 ⇹ U+21f9 LEFT RIGHT ARROW WITH VERTICAL STROKE
561 ⇼ U+21fc LEFT RIGHT ARROW WITH DOUBLE VERTICAL STROKE
562 ⇿ U+21ff LEFT RIGHT OPEN-HEADED ARROW
563 ≋ U+224b TRIPLE TILDE
564 ┄ U+2504 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL
565 ┅ U+2505 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL
566 ┈ U+2508 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL
567 ┉ U+2509 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL
568 ⧻ U+29fb TRIPLE PLUS
569 ⬌ U+2b0c LEFT RIGHT BLACK ARROW
570 chr_eli_v
572 chr_eli_v : U+21A4U+21A6
573 When using "--ellipsis" with "--verbose" level 2 or up, the single
575 character indicator will be replaced with this character. If it is 2
576 characters wide, the length of the compressed part is put between the
577 characters.
578 A suggested alternative might be U+21E4U+21E5
580
582 You can use ccdiff to show diffs in git. It may work like this:
583 $ git config --global diff.tool ccdiff
585 $ git config --global difftool.prompt false
586 $ git config --global difftool.ccdiff.cmd 'ccdiff --utf-8 -u -r $LOCAL $REMOTE'
587 $ git difftool SHA~..SHA
588 $ wget https://github.com/Tux/App-ccdiff/raw/master/Files/git-ccdiff \
589 -O ~/bin/git-ccdiff
590 $ perl -pi -e 's{/pro/bin/perl}{/usr/bin/env perl}' ~/bin/git-ccdiff
591 $ chmod 755 ~/bin/git-ccdiff
592 $ git ccdiff SHA
593 Of course you can use "curl" instead of "wget" and you can choose your
595 own (fixed) path to "perl" instead of using "/usr/bin/env".
596 From then on you can do
598 $ git ccdiff
600 $ git ccdiff 5c5a39f2
601
603 Due to the implementation, where both sides of the comparison are
604 completely kept in memory, this tool might not be able to deal with
605 (very) large datasets.
606 Speed
608 There are situations where Algorithm::Diff takes considerably more time
609 compared to e.g. GNU diff. Installing Algorithm::Diff::XS will make
610 "ccdiff" a lot faster. "ccdiff" will choose Algorithm::Diff::XS if
611 available.
612
614 Algorithm::Diff::XS, Algorithm::Diff, Text::Diff
615
617 H.Merijn Brand
618
620 Copyright (C) 2018-2023 H.Merijn Brand. All rights reserved.
621 This library is free software; you can redistribute and/or modify it
623 under the same terms as The Artistic License 2.0.
624perl v5.38.0 2023-11-18 App::ccdiff(3)