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 op 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 options 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       --list-colors
170         List available colors and exit.
171
172       --no-colors
173         Disable all colors. Useful for redirecting the diff output to a file
174         that is to be included in documentation.
175
176       --old=color
177         Define the foreground color for deleted text.
178
179       --new=color
180         Define the foreground color for added text.
181
182       --bg=color
183         Define the background color for changed text.
184
185       --index --idx -I
186         Prefix position indicators with an index.
187
188          [001] 5,5c5,5
189          -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
190          +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
191
192         If a positive number is passed ("--index=4" or "-I 4"), display just
193         the chunk with that index, using the "verbose" color:
194
195         This is useful in combination with "--verbose".
196
197       --threshold=2 -t 2
198         Defines the number of lines a change block may differ before the
199         fall-back of horizontal diff to vertical diff.
200
201         If a chunk describes a change, and the number of lines in the
202         original block has less or more lines than the new block and that
203         difference exceeds this threshold, "ccdiff" will fall-back to
204         vertical diff.
205
206       --heuristics=n -h n
207         Defines the percentage of character-changes a change block may differ
208         before the fall-back of horizontal diff to vertical diff.
209
210         This percentage is calculated as "(characters removed + characters
211         added) / (2 * characters unchanged))".
212
213       --ellipsis=n -e n
214         Defines the number of characters to keep on each side of a
215         horizontal-equal segment. The default is 0, meaning do not compress.
216
217         If set to a positive number, and the length of a segment of equal
218         characters inside a horizontal diff is longer than twice this value,
219         the middle part is replaced with "┈ U02508 \N{BOX DRAWINGS LIGHT
220         QUADRUPLE DASH HORIZONTAL}" (instead of … U02026, as HORIZONTAL
221         ELLIPSIS does not stand out enough).
222
223         With "-u0me3" that would be like
224
225          5,5c5,5
226          -Sat┈07:08:33┈ 1998,I.┈539
227          -        ▼        ▼
228          +Sat┈07:00:33┈ 1993,I.┈539
229          +        ▲        ▲
230
231         With "-u0e3 -v2" like
232
233          5,5c5,5
234          -Sat↤9↦07:0↱0↰:33 199↱3↰,I.↤23↦539
235          - -- verbose : DIGIT ZERO, DIGIT THREE
236          +Sat↤9↦07:0↱8↰:33 199↱8↰,I.↤23↦539
237          + -- verbose : DIGIT EIGHT, DIGIT EIGHT
238
239         The text used for the replaced text can be defined in your
240         configuration file as "chr_eli" and/or "chr_eli_v".
241
242       --ignore-case -i
243         Ignore case on comparison.
244
245       --ignore-all-space -w
246         Ignore all white-space changes. This will set all options "-b", "-Z",
247         "-E", and "-B".
248
249       --ignore-trailing-space -Z
250         Ignore changes in trailing white-space (TAB's and spaces).
251
252       --ignore-ws|ignore-space-change -b
253         Ignore changes in horizontal white-space (TAB's and spaces). This
254         does not include white-space changes that splits non-white-space or
255         removes white-space between two non-white-space elements.
256
257       --ignore-tab-expansion -E
258         NYI
259
260       --ignore-blank-lines -B
261         Just Partly Implemented (WIP)
262
263   Configuration files
264       In order to be able to overrule the defaults set in "ccdiff", one can
265       set options specific for this login. The following option files are
266       looked for in this order:
267
268        - $HOME/ccdiff.rc
269        - $HOME/.ccdiffrc
270        - $HOME/.config/ccdiff
271
272       and evaluated in that order. Any options specified in a file later in
273       that chain will overwrite previously set options.
274
275       Option files are only read and evaluated if it is not empty and not
276       writable by others than the owner.
277
278       The syntax of the file is one option per line. where leading and
279       trailing white-space is ignored. If that line then starts with one of
280       the options listed below, followed by optional white-space followed by
281       either an "=" or a ":", followed by optional white-space and the
282       values, the value is assigned to the option. The values "no" and
283       "false" (case insensitive) are aliases for 0. The values "yes" and
284       "true" are aliases to "-1" ("-1" being a true value).
285
286       Between parens is the corresponding command-line option.
287
288       unified (-u)
289         If you prefer unified-diff over old-style diff by default, set this
290         to the desired number of context lines:
291
292          unified : 3
293
294         The default is undefined
295
296       markers (-m)
297          markers : false
298
299         Defines if markers should be used under changed characters. The
300         default is to use colors only. The "-m" command line option will
301         toggle the option when set from a configuration file.
302
303       ascii (-a)
304          ascii   : false
305
306         Defines to use ASCII markers instead of Unicode markers. The default
307         is to use Unicode markers.
308
309       reverse (-r)
310          reverse : false
311
312         Defines if changes are displayed as foreground-color over background-
313         color or background-color over foreground-color. The default is
314         "false", so it will color the changes with the appropriate color
315         ("new" or "old") over the default background color.
316
317       new (--new)
318          new     : green
319
320         Defines the color to be used for added text. The default is "green".
321
322         The color "none" is also accepted and disables this color.
323
324         Any color accepted by Term::ANSIColor is allowed. Any other color
325         will result in a warning. This option can include "bold" either as
326         prefix or as suffix.
327
328         This option may also be specified as
329
330          new-color
331          new_color
332          new-colour
333          new_colour
334
335       old (--old)
336          old     : red
337
338         Defines the color to be used for delete text. The default is "red".
339
340         The color "none" is also accepted and disables this color.
341
342         Any color accepted by Term::ANSIColor is allowed. Any other color
343         will result in a warning. This option can include "bold" either as
344         prefix or as suffix.
345
346         This option may also be specified as
347
348          old-color
349          old_color
350          old-colour
351          old_colour
352
353       bg (--bg)
354          bg      : white
355
356         Defines the color to be used as background for changed text. The
357         default is "white".
358
359         The color "none" is also accepted and disables this color.
360
361         Any color accepted by Term::ANSIColor is allowed. Any other color
362         will result in a warning. The "bold" attribute is not allowed.
363
364         This option may also be specified as
365
366          bg-color
367          bg_color
368          bg-colour
369          bg_colour
370          background
371          background-color
372          background_color
373          background-colour
374          background_colour
375
376       verbose
377          verbose : cyan
378
379         Defines the color to be used as color for the verbose tag. The
380         default is "cyan". This color will only be used under "--verbose".
381
382         The color "none" is also accepted and disables this color.
383
384         Any color accepted by Term::ANSIColor is allowed. Any other color
385         will result in a warning.
386
387         This option may also be specified as
388
389          verbose-color
390          verbose_color
391          verbose-colour
392          verbose_colour
393
394       utf8 (-U)
395          utf8    : yes
396
397         Defines whether all I/O is to be interpreted as UTF-8. The default is
398         "no".
399
400         This option may also be specified as
401
402          unicode
403          utf
404          utf-8
405
406       index (-I)
407          index   : no
408
409         Defines if the position indication for a change chunk is prefixed
410         with an index number. The default is "no". The index is 1-based.
411
412         Without this option, the position indication would be like
413
414          5,5c5,5
415          19,19d18
416          42a42,42
417
418         with this option, it would be
419
420          [001] 5,5c5,5
421          [002] 19,19d18
422          [005] 42a42,42
423
424         When this option contains a positive integer, "ccdiff" will only show
425         diff the diff chunk with that index.
426
427       emacs
428          emacs   : no
429
430         If this option is yes/true, calling "ccdiff" with just one single
431         argument, and that argument being an existing file, the arguments
432         will act as
433
434          $ ccdiff file~ file
435
436         if file~ exists.
437
438       threshold (-t)
439          threshold : 2
440
441         Defines the number of lines a change block may differ before the
442         fall-back of horizontal diff to vertical diff.
443
444       heuristics (-h)
445          heuristics : 40
446
447         Defines the percentage of character-changes a change block may differ
448         before the fall-back of horizontal diff to vertical diff. The default
449         is undefined, meaning no fallback based on heuristics.
450
451       ellipsis (-e)
452          ellipsis : 0
453
454         Defines the number of characters to keep on each side of a
455         horizontal-equal segment. The default is 0, meaning to not compress.
456         See also "chr_eli".
457
458       chr_old
459          chr_old : U+25BC
460
461         Defines the character used to indicate the position of removed text
462         on the line below the text when option "-m" is in effect.
463
464       chr_new
465          chr_new : U+25B2
466
467         Defines the character used to indicate the position of added text on
468         the line below the text when option "-m" is in effect.
469
470       chr_cml
471          chr_cml : U+21B1
472
473         Defines the character used to indicate the starting position of
474         changed text in a line when verbose level is 3 and up.
475
476       chr_cmr
477          chr_cmr : U+21B0
478
479         Defines the character used to indicate the ending position of changed
480         text in a line when verbose level is 3 and up.
481
482       chr_eli
483          chr_eli : U+21B0
484
485         Defines the character used to indicate omitted text in large
486         unchanged text when "--ellipsis"/"-e" is in effect.
487
488         This character is not equally well visible on all terminals or in all
489         fonts, so you might want to chane it to something that stands out
490         better in you environment. Possible suggestions:
491
492          … U+2026 HORIZONTAL ELLIPSIS
493          ‴ U+2034 TRIPLE PRIME
494          ‷ U+2037 REVERSED TRIPLE PRIME
495          ↔ U+2194 LEFT RIGHT ARROW
496          ↭ U+21ad LEFT RIGHT WAVE ARROW
497          ↮ U+21ae LEFT RIGHT ARROW WITH STROKE
498          ↹ U+21b9 LEFTWARDS ARROW TO BAR OVER RIGHTWARDS ARROW TO BAR
499          ⇄ U+21c4 RIGHTWARDS ARROW OVER LEFTWARDS ARROW
500          ⇆ U+21c6 LEFTWARDS ARROW OVER RIGHTWARDS ARROW
501          ⇎ U+21ce LEFT RIGHT DOUBLE ARROW WITH STROKE
502          ⇔ U+21d4 LEFT RIGHT DOUBLE ARROW
503          ⇹ U+21f9 LEFT RIGHT ARROW WITH VERTICAL STROKE
504          ⇼ U+21fc LEFT RIGHT ARROW WITH DOUBLE VERTICAL STROKE
505          ⇿ U+21ff LEFT RIGHT OPEN-HEADED ARROW
506          ≋ U+224b TRIPLE TILDE
507          ┄ U+2504 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL
508          ┅ U+2505 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL
509          ┈ U+2508 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL
510          ┉ U+2509 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL
511          ⧻ U+29fb TRIPLE PLUS
512          ⬌ U+2b0c LEFT RIGHT BLACK ARROW
513
514       chr_eli_v
515          chr_eli_v : U+21A4U+21A6
516
517         When ussing "--ellipsis" with "--verbose" level 2 or up, the single
518         character indicator will be replaced with this character. If it is 2
519         characters wide, the length of the compressed part is put between the
520         characters.
521
522         A suggested alternative might be U+21E4U+21E5
523

Git integration

525       You can use ccdiff to show diffs in git. It may work like this:
526
527        $ git config --global diff.tool ccdiff
528        $ git config --global difftool.prompt false
529        $ git config --global difftool.ccdiff.cmd 'ccdiff --utf-8 -u -r $LOCAL $REMOTE'
530        $ git difftool SHA~..SHA
531        $ wget https://github.com/Tux/App-ccdiff/blob/master/Files/git-ccdiff \
532           -O ~/bin/git-ccdiff
533        $ perl -pi -e 's{/pro/bin/perl}{/usr/bin/env perl}' ~/bin/git-ccdiff
534        $ chmod 755 ~/bin/git-ccdiff
535        $ git ccdiff SHA
536
537       Of course you can use "curl" instead of "wget" and you can choose your
538       own (fixed) path to "perl" instead of using "/usr/bin/env".
539
540       From then on you can do
541
542        $ git ccdiff
543        $ git ccdiff 5c5a39f2
544

CAVEATS

546       Due to the implementation, where both sides of the comparison are
547       completely kept in memory, this tool might not be able to deal with
548       (very) large datasets.
549

SEE ALSO

551       Algorithm::Diff, Text::Diff
552

AUTHOR

554       H.Merijn Brand
555
557        Copyright (C) 2018-2018 H.Merijn Brand.  All rights reserved.
558
559       This library is free software;  you can redistribute and/or modify it
560       under the same terms as The Artistic License 2.0.
561
562
563
564perl v5.28.1                      2018-10-09                    App::ccdiff(3)
Impressum