1App::ccdiff(3)        User Contributed Perl Documentation       App::ccdiff(3)
2
3
4

NAME

6       ccdiff - Colored Character diff
7

SYNOPSIS

9        ccdiff [options] file1|- file2|-
10        ccdiff [options] dir1    dir2
11
12        ccdiff --help
13        ccdiff --man
14        ccdiff --info
15

DESCRIPTION

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
23       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

OPTIONS

27   Command line options
28       --help -?
29         Show a summary of the available command-line options and exit.
30
31       --version -V
32         Show the version and exit.
33
34       --man
35         Show this manual using pod2man and nroff.
36
37       --info
38         Show this manual using pod2text.
39
40       --utf-8 -U
41         All I/O (streams to compare and standard out) are in UTF-8.
42
43       --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
48         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
51         Select the pure-perl version with any of "PP", "AD",
52         "Algorthm::Diff", "Algorithm-Diff", or "Algorithm::Diff::PP" (case
53         insensitive)
54
55          --dc=pp
56          --dc=algorithm-diff
57          --diff-class=Algorithm::Diff::PP
58
59         Select the XS version with any of "XS", "ADX", "Algorthm::Diff::XS",
60         or "Algorithm-Diff-XS" (case insensitive)
61
62          --dc=xs
63          --dc=algorithm-diff-xs
64          --diff-class=Algorithm::Diff::XS
65
66       --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
73         The default is to use traditional diff:
74
75          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
80         a unified diff (-u1) would be
81
82          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
88       --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
94         This is a debugging option, so invisible characters can still be
95         "seen".
96
97         "--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
103         An example of this:
104
105         With -Uu0v0:
106
107          1,1c1,1
108          - A  BCDE Fg
109          + A BcdEFg
110
111         With -Uu0v1:
112
113          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
119         With -Uu0v2:
120
121          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
127         With -Uu0v3:
128
129          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
135         With -Uu0v2 --ascii:
136
137          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
143         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
149       --markers -m
150         Use markers under each changed character in change-chunks.
151
152         "--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
157         This will look like (with unified diff):
158
159          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
165         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
170         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
174       --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
179         For the vertical markers ("-m") that would look like:
180
181          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
187         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
191       --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
195       --reverse -r
196         Reverse/invert the foreground and background for the colored
197         indicators.
198
199         If the foreground color has "bold", it will be stripped from the new
200         background color.
201
202       --swap -s
203         Swap the colors for new and old.
204
205       --list-colors
206         List available colors and exit.
207
208       --no-colors
209         Disable all colors. Useful for redirecting the diff output to a file
210         that is to be included in documentation.
211
212         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
217       --old=color
218         Define the foreground color for deleted text.
219
220       --new=color
221         Define the foreground color for added text.
222
223       --bg=color
224         Define the background color for changed text.
225
226       --index --idx -I
227         Prefix position indicators with an index.
228
229          [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
233         If a positive number is passed ("--index=4" or "-I 4"), display just
234         the chunk with that index, using the "verbose" color:
235
236         This is useful in combination with "--verbose".
237
238       --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
242         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
247       --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
251         This percentage is calculated as "(characters removed + characters
252         added) / (2 * characters unchanged))".
253
254       --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
258         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
264         With "-u0me3" that would be like
265
266          5,5c5,5
267          -Sat┈07:08:33┈ 1998,I.┈539
268          -        ▼        ▼
269          +Sat┈07:00:33┈ 1993,I.┈539
270          +        ▲        ▲
271
272         With "-u0e3 -v2" like
273
274          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
280         The text used for the replaced text can be defined in your
281         configuration file as "chr_eli" and/or "chr_eli_v".
282
283       --ignore-case -i
284         Ignore case on comparison.
285
286       --ignore-all-space -w
287         Ignore all white-space changes. This will set all options "-b", "-Z",
288         "-E", and "-B".
289
290       --ignore-trailing-space -Z
291         Ignore changes in trailing white-space (tabs and spaces).
292
293       --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
298       --ignore-tab-expansion -E
299         NYI
300
301       --ignore-blank-lines -B
302         Just Partly Implemented (WIP)
303
304   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
309        - $HOME/ccdiff.rc
310        - $HOME/.ccdiffrc
311        - $HOME/.config/ccdiff
312
313       and evaluated in that order. Any options specified in a file later in
314       that chain will overwrite previously set options.
315
316       Option files are only read and evaluated if they are not empty and not
317       writable by others than the owner.
318
319       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
327       Between parens is the corresponding command-line option.
328
329       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
333          unified : 3
334
335         The default is undefined
336
337       markers (-m)
338          markers : false
339
340         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
344       ascii (-a)
345          ascii   : false
346
347         Defines to use ASCII markers instead of Unicode markers. The default
348         is to use Unicode markers.
349
350       reverse (-r)
351          reverse : false
352
353         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
358       swap (-s)
359          swap    : false
360
361         Swap the colors for new and old.
362
363       new (--new)
364          new     : green
365
366         Defines the color to be used for added text. The default is "green".
367
368         The color "none" is also accepted and disables this color.
369
370         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
374         This option may also be specified as
375
376          new-color
377          new_color
378          new-colour
379          new_colour
380
381       old (--old)
382          old     : red
383
384         Defines the color to be used for deleted text. The default is "red".
385
386         The color "none" is also accepted and disables this color.
387
388         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
392         This option may also be specified as
393
394          old-color
395          old_color
396          old-colour
397          old_colour
398
399       bg (--bg)
400          bg      : white
401
402         Defines the color to be used as background for changed text. The
403         default is "white".
404
405         The color "none" is also accepted and disables this color.
406
407         Any color accepted by Term::ANSIColor is allowed. Any other color
408         will result in a warning. The "bold" attribute is not allowed.
409
410         This option may also be specified as
411
412          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
422       header (-H --header --HC=color --header-color=color)
423          header  : 1
424          header  : blue_on_white
425
426         Defines if a header is displayed above the diff (default is 1),
427         supported colors are allowed.
428
429         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
433       verbose
434          verbose : cyan
435
436         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
439         The color "none" is also accepted and disables this color.
440
441         Any color accepted by Term::ANSIColor is allowed. Any other color
442         will result in a warning.
443
444         This option may also be specified as
445
446          verbose-color
447          verbose_color
448          verbose-colour
449          verbose_colour
450
451       utf8 (-U)
452          utf8    : yes
453
454         Defines whether all I/O is to be interpreted as UTF-8. The default is
455         "no".
456
457         This option may also be specified as
458
459          unicode
460          utf
461          utf-8
462
463       index (-I)
464          index   : no
465
466         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
469         Without this option, the position indication would be like
470
471          5,5c5,5
472          19,19d18
473          42a42,42
474
475         with this option, it would be
476
477          [001] 5,5c5,5
478          [002] 19,19d18
479          [005] 42a42,42
480
481         When this option contains a positive integer, "ccdiff" will only show
482         the diff chunk with that index.
483
484       emacs
485          emacs   : no
486
487         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
491          $ ccdiff file~ file
492
493         if file~ exists.
494
495       threshold (-t)
496          threshold : 2
497
498         Defines the number of lines a change block may differ before the
499         fall-back of horizontal diff to vertical diff.
500
501       heuristics (-h)
502          heuristics : 40
503
504         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
508       ellipsis (-e)
509          ellipsis : 0
510
511         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
515       chr_old
516          chr_old : U+25BC
517
518         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
521       chr_new
522          chr_new : U+25B2
523
524         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
527       chr_cml
528          chr_cml : U+21B1
529
530         Defines the character used to indicate the starting position of
531         changed text in a line when verbose level is 3 and up.
532
533       chr_cmr
534          chr_cmr : U+21B0
535
536         Defines the character used to indicate the ending position of changed
537         text in a line when verbose level is 3 and up.
538
539       chr_eli
540          chr_eli : U+21B0
541
542         Defines the character used to indicate omitted text in large
543         unchanged text when "--ellipsis"/"-e" is in effect.
544
545         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
549          … 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
571       chr_eli_v
572          chr_eli_v : U+21A4U+21A6
573
574         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
579         A suggested alternative might be U+21E4U+21E5
580

Git integration

582       You can use ccdiff to show diffs in git. It may work like this:
583
584        $ 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
594       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
597       From then on you can do
598
599        $ git ccdiff
600        $ git ccdiff 5c5a39f2
601

CAVEATS

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
607   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

SEE ALSO

614       Algorithm::Diff::XS, Algorithm::Diff, Text::Diff
615

AUTHOR

617       H.Merijn Brand
618
620        Copyright (C) 2018-2023 H.Merijn Brand.  All rights reserved.
621
622       This library is free software;  you can redistribute and/or modify it
623       under the same terms as The Artistic License 2.0.
624
625
626
627perl v5.38.0                      2023-11-18                    App::ccdiff(3)
Impressum