1App::ccdiff(3) User Contributed Perl Documentation App::ccdiff(3)
2
6 ccdiff - Colored Character diff
7
9 ccdiff [options] file1|- file2|-
10 ccdiff --help
12 ccdiff --man
13 ccdiff --info
14
17 Command line options
18 --help -?
19 Show a summary of the available command-line options and exit.
20 --version -V
22 Show the version and exit.
23 --man
25 Show this manual using pod2man and nroff.
26 --info
28 Show this manual using pod2text.
29 --utf-8 -U
31 All I/O (streams to compare and standard out) are in UTF-8.
32 --unified[=3] -u [3]
34 Generate a unified diff. The number of context lines is optional.
35 When omitted it defaults to 3. Currently there is no provision of
36 dealing with overlapping diff chunks. If the common part between two
37 diff chunks is shorter than twice the number of context lines, some
38 lines may show twice.
39 The default is to use traditional diff:
41 5,5c5,5
43 < Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
44 ---
45 > Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
46 a unified diff (-u1) would be
48 5,5c5,5
50 Tue Sep 6 05:43:59 2005,B.O.Q.S.,,1125978239,1943341
51 -Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
52 +Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
53 Mon Feb 23 10:37:02 2004,R.X.K.S.,van,1077529022,1654127
54 --verbose[=1] -v[1]
56 Show an additional line for each old or new section in a change chunk
57 (not for added or deleted lines) that shows the hexadecimal value of
58 each character. If "--utf-8" is in effect, it will show the Unicode
59 character name(s).
60 This is a debugging option, so invisible characters can still be
62 "seen".
63 "--verbose" accepts an optional verbosity-level. On level 2 and up,
65 all horizontal changes get left-and-right markers inserted to enable
66 seeing the location of the ZERO WIDTH or invisible characters. With
67 level 3 and up and Unicode enabled, the changed characters will also
68 show the codepoint in hex.
69 An example of this:
71 With -Uu0v0:
73 1,1c1,1
75 - A BCDE Fg
76 + A BcdEFg
77 With -Uu0v1:
79 1,1c1,1
81 - A BCDE Fg
82 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
83 + A BcdEFg
84 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
85 With -Uu0v2:
87 1,1c1,1
89 - A ↱ ↰B↱CD↰E↱ ↰Fg
90 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
91 + A B↱cd↰E↱↰Fg
92 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
93 With -Uu0v3:
95 1,1c1,1
97 - A ↱ ↰B↱CD↰E↱ ↰Fg
98 - -- verbose : SPACE (U+000020), LATIN CAPITAL LETTER C (U+000043), LATIN CAPITAL LETTER D (U+000044), SPACE (U+000020)
99 + A B↱cd↰E↱↰Fg
100 + -- verbose : LATIN SMALL LETTER C (U+000063), LATIN SMALL LETTER D (U+000064), ZERO WIDTH SPACE (U+00200B)
101 With -Uu0v2 --ascii:
103 1,1c1,1
105 - A > <B>CD<E> <Fg
106 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
107 + A B>cd<E><Fg
108 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
109 the word "verbose" and the character markers will be displayed using
111 the "verbose" color. The characters used for the markers can be
112 defined in your configuration file as "chr_cml" (the character used
113 as marker on the left) and "chr_cmr" (the character used as marker on
114 the right).
115 --markers -m
117 Use markers under each changed character in change-chunks.
118 "--markers" is especially useful if the terminal does not support
120 colors, or if you want to copy/paste the output to (ASCII) mail. See
121 also "--ascii". The markers will have the same color as added or
122 deleted text.
123 This will look like (with unified diff):
125 5,5c5,5
127 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
128 - ▼ ▼
129 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
130 + ▲ ▲
131 The characters used for the markers can be defined in your
133 configuration file as "chr_old" (the character used as marker under
134 removed characters) and "chr_new" (the character used as marker under
135 added characters).
136 If "--ellipsis" is also in effect and either the "chr_eli" is longer
138 than one character or "--verbose" level is over 2, this option is
139 automatically disabled.
140 --ascii -a
142 Use (colored) ASCII indicators instead of Unicode. The default
143 indicators are Unicode characters that stand out better. The markers
144 will have the same color as added or deleted text.
145 For the vertical markers ("-m") that would look like:
147 5,5c5,5
149 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
150 - ^ ^
151 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
152 + ^ ^
153 For the positional indicators, I did consider using U+034e (COMBINING
155 UPWARDS ARROW BELOW), but as most terminals are probably unable to
156 show it due to line height changes, I did not pursue the idea.
157 --pink -p
159 Change the default "red" for deleted text to the color closest to
160 pink that is supported by Term::ANSIColor: "magenta".
161 --reverse -r
163 Reverse/invert the foreground and background for the colored
164 indicators.
165 If the foreground color has "bold", it will be stripped from the new
167 background color.
168 --swap -s
170 Swap the colors for new and old.
171 --list-colors
173 List available colors and exit.
174 --no-colors
176 Disable all colors. Useful for redirecting the diff output to a file
177 that is to be included in documentation.
178 This is the default if the environment variable $NO_COLOR has a true
180 value or if the environment variable $CLICOLOR is set to a false
181 value. If set, $CLICOLOR_FORCE will overrule the default of
182 $NO_COLOR.
183 --old=color
185 Define the foreground color for deleted text.
186 --new=color
188 Define the foreground color for added text.
189 --bg=color
191 Define the background color for changed text.
192 --index --idx -I
194 Prefix position indicators with an index.
195 [001] 5,5c5,5
197 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
198 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
199 If a positive number is passed ("--index=4" or "-I 4"), display just
201 the chunk with that index, using the "verbose" color:
202 This is useful in combination with "--verbose".
204 --threshold=2 -t 2
206 Defines the number of lines a change block may differ before the
207 fall-back of horizontal diff to vertical diff.
208 If a chunk describes a change, and the number of lines in the
210 original block has fewer or more lines than the new block and that
211 difference exceeds this threshold, "ccdiff" will fall-back to
212 vertical diff.
213 --heuristics=n -h n
215 Defines the percentage of character-changes a change block may differ
216 before the fall-back of horizontal diff to vertical diff.
217 This percentage is calculated as "(characters removed + characters
219 added) / (2 * characters unchanged))".
220 --ellipsis=n -e n
222 Defines the number of characters to keep on each side of a
223 horizontal-equal segment. The default is 0, meaning do not compress.
224 If set to a positive number, and the length of a segment of equal
226 characters inside a horizontal diff is longer than twice this value,
227 the middle part is replaced with "┈ U02508 \N{BOX DRAWINGS LIGHT
228 QUADRUPLE DASH HORIZONTAL}" (instead of … U02026, as HORIZONTAL
229 ELLIPSIS does not stand out enough).
230 With "-u0me3" that would be like
232 5,5c5,5
234 -Sat┈07:08:33┈ 1998,I.┈539
235 - ▼ ▼
236 +Sat┈07:00:33┈ 1993,I.┈539
237 + ▲ ▲
238 With "-u0e3 -v2" like
240 5,5c5,5
242 -Sat↤9↦07:0↱0↰:33 199↱3↰,I.↤23↦539
243 - -- verbose : DIGIT ZERO, DIGIT THREE
244 +Sat↤9↦07:0↱8↰:33 199↱8↰,I.↤23↦539
245 + -- verbose : DIGIT EIGHT, DIGIT EIGHT
246 The text used for the replaced text can be defined in your
248 configuration file as "chr_eli" and/or "chr_eli_v".
249 --ignore-case -i
251 Ignore case on comparison.
252 --ignore-all-space -w
254 Ignore all white-space changes. This will set all options "-b", "-Z",
255 "-E", and "-B".
256 --ignore-trailing-space -Z
258 Ignore changes in trailing white-space (tabs and spaces).
259 --ignore-ws|ignore-space-change -b
261 Ignore changes in horizontal white-space (tabs and spaces). This does
262 not include white-space changes that split non-white-space or remove
263 white-space between two non-white-space elements.
264 --ignore-tab-expansion -E
266 NYI
267 --ignore-blank-lines -B
269 Just Partly Implemented (WIP)
270 Configuration files
272 In order to be able to overrule the defaults set in "ccdiff", one can
273 set options specific for this login. The following option files are
274 looked for in this order:
275 - $HOME/ccdiff.rc
277 - $HOME/.ccdiffrc
278 - $HOME/.config/ccdiff
279 and evaluated in that order. Any options specified in a file later in
281 that chain will overwrite previously set options.
282 Option files are only read and evaluated if they are not empty and not
284 writable by others than the owner.
285 The syntax of the file is one option per line, where leading and
287 trailing white-space is ignored. If that line then starts with one of
288 the options listed below, followed by optional white-space followed by
289 either an "=" or a ":", followed by optional white-space and the
290 values, the value is assigned to the option. The values "no" and
291 "false" (case insensitive) are aliases for 0. The values "yes" and
292 "true" are aliases to "-1" ("-1" being a true value).
293 Between parens is the corresponding command-line option.
295 unified (-u)
297 If you prefer unified-diff over old-style diff by default, set this
298 to the desired number of context lines:
299 unified : 3
301 The default is undefined
303 markers (-m)
305 markers : false
306 Defines if markers should be used under changed characters. The
308 default is to use colors only. The "-m" command line option will
309 toggle the option when set from a configuration file.
310 ascii (-a)
312 ascii : false
313 Defines to use ASCII markers instead of Unicode markers. The default
315 is to use Unicode markers.
316 reverse (-r)
318 reverse : false
319 Defines if changes are displayed as foreground-color over background-
321 color or background-color over foreground-color. The default is
322 "false", so it will color the changes with the appropriate color
323 ("new" or "old") over the default background color.
324 swap (-s)
326 swap : false
327 Swap the colors for new and old.
329 new (--new)
331 new : green
332 Defines the color to be used for added text. The default is "green".
334 The color "none" is also accepted and disables this color.
336 Any color accepted by Term::ANSIColor is allowed. Any other color
338 will result in a warning. This option can include "bold" either as
339 prefix or as suffix.
340 This option may also be specified as
342 new-color
344 new_color
345 new-colour
346 new_colour
347 old (--old)
349 old : red
350 Defines the color to be used for deleted text. The default is "red".
352 The color "none" is also accepted and disables this color.
354 Any color accepted by Term::ANSIColor is allowed. Any other color
356 will result in a warning. This option can include "bold" either as
357 prefix or as suffix.
358 This option may also be specified as
360 old-color
362 old_color
363 old-colour
364 old_colour
365 bg (--bg)
367 bg : white
368 Defines the color to be used as background for changed text. The
370 default is "white".
371 The color "none" is also accepted and disables this color.
373 Any color accepted by Term::ANSIColor is allowed. Any other color
375 will result in a warning. The "bold" attribute is not allowed.
376 This option may also be specified as
378 bg-color
380 bg_color
381 bg-colour
382 bg_colour
383 background
384 background-color
385 background_color
386 background-colour
387 background_colour
388 header (-H --header --HC=color --header-color=color)
390 header : 1
391 header : blue_on_white
392 Defines if a header is displayed above the diff (default is 1),
394 supported colors are allowed.
395 If the value is a valid supported color, it will show the header in
397 that color scheme. To disable the header set it to 0 in the RC file
398 or use "--no-header" as a command line argument.
399 verbose
401 verbose : cyan
402 Defines the color to be used as color for the verbose tag. The
404 default is "cyan". This color will only be used under "--verbose".
405 The color "none" is also accepted and disables this color.
407 Any color accepted by Term::ANSIColor is allowed. Any other color
409 will result in a warning.
410 This option may also be specified as
412 verbose-color
414 verbose_color
415 verbose-colour
416 verbose_colour
417 utf8 (-U)
419 utf8 : yes
420 Defines whether all I/O is to be interpreted as UTF-8. The default is
422 "no".
423 This option may also be specified as
425 unicode
427 utf
428 utf-8
429 index (-I)
431 index : no
432 Defines if the position indication for a change chunk is prefixed
434 with an index number. The default is "no". The index is 1-based.
435 Without this option, the position indication would be like
437 5,5c5,5
439 19,19d18
440 42a42,42
441 with this option, it would be
443 [001] 5,5c5,5
445 [002] 19,19d18
446 [005] 42a42,42
447 When this option contains a positive integer, "ccdiff" will only show
449 the diff chunk with that index.
450 emacs
452 emacs : no
453 If this option is yes/true, calling "ccdiff" with just one single
455 argument, and that argument being an existing file, the arguments
456 will act as
457 $ ccdiff file~ file
459 if file~ exists.
461 threshold (-t)
463 threshold : 2
464 Defines the number of lines a change block may differ before the
466 fall-back of horizontal diff to vertical diff.
467 heuristics (-h)
469 heuristics : 40
470 Defines the percentage of character-changes a change block may differ
472 before the fall-back of horizontal diff to vertical diff. The default
473 is undefined, meaning no fallback based on heuristics.
474 ellipsis (-e)
476 ellipsis : 0
477 Defines the number of characters to keep on each side of a
479 horizontal-equal segment. The default is 0, meaning to not compress.
480 See also "chr_eli".
481 chr_old
483 chr_old : U+25BC
484 Defines the character used to indicate the position of removed text
486 on the line below the text when option "-m" is in effect.
487 chr_new
489 chr_new : U+25B2
490 Defines the character used to indicate the position of added text on
492 the line below the text when option "-m" is in effect.
493 chr_cml
495 chr_cml : U+21B1
496 Defines the character used to indicate the starting position of
498 changed text in a line when verbose level is 3 and up.
499 chr_cmr
501 chr_cmr : U+21B0
502 Defines the character used to indicate the ending position of changed
504 text in a line when verbose level is 3 and up.
505 chr_eli
507 chr_eli : U+21B0
508 Defines the character used to indicate omitted text in large
510 unchanged text when "--ellipsis"/"-e" is in effect.
511 This character is not equally well visible on all terminals or in all
513 fonts, so you might want to change it to something that stands out
514 better in your environment. Possible suggestions:
515 … U+2026 HORIZONTAL ELLIPSIS
517 ‴ U+2034 TRIPLE PRIME
518 ‷ U+2037 REVERSED TRIPLE PRIME
519 ↔ U+2194 LEFT RIGHT ARROW
520 ↭ U+21ad LEFT RIGHT WAVE ARROW
521 ↮ U+21ae LEFT RIGHT ARROW WITH STROKE
522 ↹ U+21b9 LEFTWARDS ARROW TO BAR OVER RIGHTWARDS ARROW TO BAR
523 ⇄ U+21c4 RIGHTWARDS ARROW OVER LEFTWARDS ARROW
524 ⇆ U+21c6 LEFTWARDS ARROW OVER RIGHTWARDS ARROW
525 ⇎ U+21ce LEFT RIGHT DOUBLE ARROW WITH STROKE
526 ⇔ U+21d4 LEFT RIGHT DOUBLE ARROW
527 ⇹ U+21f9 LEFT RIGHT ARROW WITH VERTICAL STROKE
528 ⇼ U+21fc LEFT RIGHT ARROW WITH DOUBLE VERTICAL STROKE
529 ⇿ U+21ff LEFT RIGHT OPEN-HEADED ARROW
530 ≋ U+224b TRIPLE TILDE
531 ┄ U+2504 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL
532 ┅ U+2505 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL
533 ┈ U+2508 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL
534 ┉ U+2509 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL
535 ⧻ U+29fb TRIPLE PLUS
536 ⬌ U+2b0c LEFT RIGHT BLACK ARROW
537 chr_eli_v
539 chr_eli_v : U+21A4U+21A6
540 When using "--ellipsis" with "--verbose" level 2 or up, the single
542 character indicator will be replaced with this character. If it is 2
543 characters wide, the length of the compressed part is put between the
544 characters.
545 A suggested alternative might be U+21E4U+21E5
547
549 You can use ccdiff to show diffs in git. It may work like this:
550 $ git config --global diff.tool ccdiff
552 $ git config --global difftool.prompt false
553 $ git config --global difftool.ccdiff.cmd 'ccdiff --utf-8 -u -r $LOCAL $REMOTE'
554 $ git difftool SHA~..SHA
555 $ wget https://github.com/Tux/App-ccdiff/raw/master/Files/git-ccdiff \
556 -O ~/bin/git-ccdiff
557 $ perl -pi -e 's{/pro/bin/perl}{/usr/bin/env perl}' ~/bin/git-ccdiff
558 $ chmod 755 ~/bin/git-ccdiff
559 $ git ccdiff SHA
560 Of course you can use "curl" instead of "wget" and you can choose your
562 own (fixed) path to "perl" instead of using "/usr/bin/env".
563 From then on you can do
565 $ git ccdiff
567 $ git ccdiff 5c5a39f2
568
570 Due to the implementation, where both sides of the comparison are
571 completely kept in memory, this tool might not be able to deal with
572 (very) large datasets.
573 Speed
575 There are situations where Algorithm::Diff takes considerably more time
576 compared to e.g. GNU diff. Installing Algorithm::Diff::XS will make
577 "ccdiff" a lot faster. "ccdiff" will choose Algorithm::Diff::XS if
578 available.
579
581 Algorithm::Diff::XS, Algorithm::Diff, Text::Diff
582
584 H.Merijn Brand
585
587 Copyright (C) 2018-2023 H.Merijn Brand. All rights reserved.
588 This library is free software; you can redistribute and/or modify it
590 under the same terms as The Artistic License 2.0.
591perl v5.36.0 2023-01-08 App::ccdiff(3)