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
11        ccdiff --help
12        ccdiff --man
13        ccdiff --info
14

DESCRIPTION

OPTIONS

17   Command line options
18       --help -?
19         Show a summary of the available command-line options and exit.
20
21       --version -V
22         Show the version and exit.
23
24       --man
25         Show this manual using pod2man and nroff.
26
27       --info
28         Show this manual using pod2text.
29
30       --utf-8 -U
31         All I/O (streams to compare and standard out) are in UTF-8.
32
33       --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
40         The default is to use traditional diff:
41
42          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
47         a unified diff (-u1) would be
48
49          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
55       --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
61         This is a debugging option, so invisible characters can still be
62         "seen".
63
64         "--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
70         An example of this:
71
72         With -Uu0v0:
73
74          1,1c1,1
75          - A  BCDE Fg
76          + A BcdE​Fg
77
78         With -Uu0v1:
79
80          1,1c1,1
81          - A  BCDE Fg
82          - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
83          + A BcdE​Fg
84          + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE
85
86         With -Uu0v2:
87
88          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
94         With -Uu0v3:
95
96          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
102         With -Uu0v2 --ascii:
103
104          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
110         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
116       --markers -m
117         Use markers under each changed character in change-chunks.
118
119         "--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
124         This will look like (with unified diff):
125
126          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
132         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
137         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
141       --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
146         For the vertical markers ("-m") that would look like:
147
148          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
154         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
158       --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
162       --reverse -r
163         Reverse/invert the foreground and background for the colored
164         indicators.
165
166         If the foreground color has "bold", it will be stripped from the new
167         background color.
168
169       --swap -s
170         Swap the colors for new and old.
171
172       --list-colors
173         List available colors and exit.
174
175       --no-colors
176         Disable all colors. Useful for redirecting the diff output to a file
177         that is to be included in documentation.
178
179         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
184       --old=color
185         Define the foreground color for deleted text.
186
187       --new=color
188         Define the foreground color for added text.
189
190       --bg=color
191         Define the background color for changed text.
192
193       --index --idx -I
194         Prefix position indicators with an index.
195
196          [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
200         If a positive number is passed ("--index=4" or "-I 4"), display just
201         the chunk with that index, using the "verbose" color:
202
203         This is useful in combination with "--verbose".
204
205       --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
209         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
214       --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
218         This percentage is calculated as "(characters removed + characters
219         added) / (2 * characters unchanged))".
220
221       --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
225         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
231         With "-u0me3" that would be like
232
233          5,5c5,5
234          -Sat┈07:08:33┈ 1998,I.┈539
235          -        ▼        ▼
236          +Sat┈07:00:33┈ 1993,I.┈539
237          +        ▲        ▲
238
239         With "-u0e3 -v2" like
240
241          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
247         The text used for the replaced text can be defined in your
248         configuration file as "chr_eli" and/or "chr_eli_v".
249
250       --ignore-case -i
251         Ignore case on comparison.
252
253       --ignore-all-space -w
254         Ignore all white-space changes. This will set all options "-b", "-Z",
255         "-E", and "-B".
256
257       --ignore-trailing-space -Z
258         Ignore changes in trailing white-space (tabs and spaces).
259
260       --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
265       --ignore-tab-expansion -E
266         NYI
267
268       --ignore-blank-lines -B
269         Just Partly Implemented (WIP)
270
271   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
276        - $HOME/ccdiff.rc
277        - $HOME/.ccdiffrc
278        - $HOME/.config/ccdiff
279
280       and evaluated in that order. Any options specified in a file later in
281       that chain will overwrite previously set options.
282
283       Option files are only read and evaluated if they are not empty and not
284       writable by others than the owner.
285
286       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
294       Between parens is the corresponding command-line option.
295
296       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
300          unified : 3
301
302         The default is undefined
303
304       markers (-m)
305          markers : false
306
307         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
311       ascii (-a)
312          ascii   : false
313
314         Defines to use ASCII markers instead of Unicode markers. The default
315         is to use Unicode markers.
316
317       reverse (-r)
318          reverse : false
319
320         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
325       swap (-s)
326          swap    : false
327
328         Swap the colors for new and old.
329
330       new (--new)
331          new     : green
332
333         Defines the color to be used for added text. The default is "green".
334
335         The color "none" is also accepted and disables this color.
336
337         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
341         This option may also be specified as
342
343          new-color
344          new_color
345          new-colour
346          new_colour
347
348       old (--old)
349          old     : red
350
351         Defines the color to be used for deleted text. The default is "red".
352
353         The color "none" is also accepted and disables this color.
354
355         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
359         This option may also be specified as
360
361          old-color
362          old_color
363          old-colour
364          old_colour
365
366       bg (--bg)
367          bg      : white
368
369         Defines the color to be used as background for changed text. The
370         default is "white".
371
372         The color "none" is also accepted and disables this color.
373
374         Any color accepted by Term::ANSIColor is allowed. Any other color
375         will result in a warning. The "bold" attribute is not allowed.
376
377         This option may also be specified as
378
379          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
389       header (-H --header --HC=color --header-color=color)
390          header  : 1
391          header  : blue_on_white
392
393         Defines if a header is displayed above the diff (default is 1),
394         supported colors are allowed.
395
396         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
400       verbose
401          verbose : cyan
402
403         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
406         The color "none" is also accepted and disables this color.
407
408         Any color accepted by Term::ANSIColor is allowed. Any other color
409         will result in a warning.
410
411         This option may also be specified as
412
413          verbose-color
414          verbose_color
415          verbose-colour
416          verbose_colour
417
418       utf8 (-U)
419          utf8    : yes
420
421         Defines whether all I/O is to be interpreted as UTF-8. The default is
422         "no".
423
424         This option may also be specified as
425
426          unicode
427          utf
428          utf-8
429
430       index (-I)
431          index   : no
432
433         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
436         Without this option, the position indication would be like
437
438          5,5c5,5
439          19,19d18
440          42a42,42
441
442         with this option, it would be
443
444          [001] 5,5c5,5
445          [002] 19,19d18
446          [005] 42a42,42
447
448         When this option contains a positive integer, "ccdiff" will only show
449         the diff chunk with that index.
450
451       emacs
452          emacs   : no
453
454         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
458          $ ccdiff file~ file
459
460         if file~ exists.
461
462       threshold (-t)
463          threshold : 2
464
465         Defines the number of lines a change block may differ before the
466         fall-back of horizontal diff to vertical diff.
467
468       heuristics (-h)
469          heuristics : 40
470
471         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
475       ellipsis (-e)
476          ellipsis : 0
477
478         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
482       chr_old
483          chr_old : U+25BC
484
485         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
488       chr_new
489          chr_new : U+25B2
490
491         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
494       chr_cml
495          chr_cml : U+21B1
496
497         Defines the character used to indicate the starting position of
498         changed text in a line when verbose level is 3 and up.
499
500       chr_cmr
501          chr_cmr : U+21B0
502
503         Defines the character used to indicate the ending position of changed
504         text in a line when verbose level is 3 and up.
505
506       chr_eli
507          chr_eli : U+21B0
508
509         Defines the character used to indicate omitted text in large
510         unchanged text when "--ellipsis"/"-e" is in effect.
511
512         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
516          … 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
538       chr_eli_v
539          chr_eli_v : U+21A4U+21A6
540
541         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
546         A suggested alternative might be U+21E4U+21E5
547

Git integration

549       You can use ccdiff to show diffs in git. It may work like this:
550
551        $ 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
561       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
564       From then on you can do
565
566        $ git ccdiff
567        $ git ccdiff 5c5a39f2
568

CAVEATS

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

SEE ALSO

581       Algorithm::Diff::XS, Algorithm::Diff, Text::Diff
582

AUTHOR

584       H.Merijn Brand
585
587        Copyright (C) 2018-2023 H.Merijn Brand.  All rights reserved.
588
589       This library is free software;  you can redistribute and/or modify it
590       under the same terms as The Artistic License 2.0.
591
592
593
594perl v5.36.0                      2023-01-08                    App::ccdiff(3)
Impressum