CCDIFF(1)

📦
version 0.35 · 2 versions
, in fedora 43, fedora 44

ccdiff 💖 User Contributed Perl Documentation — CCDIFF(1)

okay so before we even start: this is the <pink>ccdiff</pink> manual page, bestie, and it is long. Part 1 is right here, more parts are coming, don't you dare close the tab 🫶

🌸 NAME 🌸

ccdiff — Colored Character diff ✨

✨ SYNOPSIS ✨

ccdiff [options] file1|- file2|-
ccdiff [options] dir1    dir2

ccdiff --help
ccdiff --man
ccdiff --info

🦋 DESCRIPTION 🦋

So the whole vibe here? It shows you the diff between two files, but like… character by character 💅. Unlike your regular boring diff tools, ccdiff takes the diff algorithm and runs it horizontally for every single line of the vertical diff, highlighting the changes. Which is honestly iconic because it catches the stuff that's lowkey impossible to spot with your eyeballs: "O" vs 0, "I" vs l vs 1, and whitespace. Not me squinting at a terminal for twenty minutes — never again 🙈.

And if you give it two arguments and they're both a folder/directory? Boom, recursive diff time, fr fr. <red>BUT</red> — this is not available when it's used as a (sub)class. Important. Remember that one.

👑 OPTIONS 👑

💅 Command line options

  • --help, -? — Shows you a lil summary of all the command-line options and then dips out (exits).
  • --version, -V — Shows the version, exits, slay.
  • --man — Shows this very manual, using pod2man and nroff.
  • --info — Shows this manual using pod2text.
  • --utf-8, -U — All I/O — that's the streams you're comparing and standard out — is in UTF-8.
  • --diff-class=C, --dc=C, --pp — Pick which class actually runs the diff. By default ccdiff grabs the first one available out of Algorithm::Diff::XS or Algorithm::Diff.

Sometimes the XS version fails on encoding 😭 and the pure-perl version just… works fine. So you can force ccdiff to use either one:

Select the pure-perl version with any of PP, AD, Algorthm::Diff, Algorithm-Diff, or Algorithm::Diff::PP (case insensitive). And for convenience, --dc=pp can be abbreviated to --pp 💫

 --pp
 --dc=pp
 --dc=algorithm-diff
 --diff-class=Algorithm::Diff::PP

Select the XS version with any of XS, ADX, Algorthm::Diff::XS, or Algorithm-Diff-XS (case insensitive).

 --dc=xs
 --dc=algorithm-diff-xs
 --diff-class=Algorithm::Diff::XS
  • --unified[=3], -u [3] — Generates a unified diff 🫶 The number of context lines is optional — leave it off and it defaults to 3. Heads up though: currently there's no provision for dealing with overlapping diff chunks. So if the common part between two diff chunks is shorter than twice the number of context lines, some lines may show up twice. Yeah. That's a thing.

The default is to use traditional diff:

 5,5c5,5
 < Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
 ---
 > Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539

a unified diff (-u1) would be

 5,5c5,5
  Tue Sep  6 05:43:59 2005,B.O.Q.S.,,1125978239,1943341
 -Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
 +Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
  Mon Feb 23 10:37:02 2004,R.X.K.S.,van,1077529022,1654127
  • --verbose[=1], -v[1] — Shows an extra line for every old or new section inside a change chunk (not for added or deleted lines) that shows the hexadecimal value of each character. And if --utf-8 is in effect, it shows the Unicode character name(s) instead. 👀

This is a debugging option, which is the whole point — it's so invisible characters can still be "seen". Periodt.

--verbose accepts an optional verbosity-level. On level 2 and up, all horizontal changes get left-and-right markers inserted so you can actually see where the ZERO WIDTH or invisible characters are sitting. With level 3 and up, plus Unicode enabled, the changed characters also show the codepoint in hex. 🔥

An example of this:

With -Uu0v0:

 1,1c1,1
 - A  BCDE Fg
 + A BcdEFg

With -Uu0v1:

 1,1c1,1
 - A  BCDE Fg
 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
 + A BcdEFg
 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE

With -Uu0v2:

 1,1c1,1
 - A ↱ ↰B↱CD↰E↱ ↰Fg
 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
 + A B↱cd↰E↱↰Fg
 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE

With -Uu0v3:

 1,1c1,1
 - A ↱ ↰B↱CD↰E↱ ↰Fg
 - -- verbose : SPACE (U+000020), LATIN CAPITAL LETTER C (U+000043), LATIN CAPITAL LETTER D (U+000044), SPACE (U+000020)
 + A B↱cd↰E↱↰Fg
 + -- verbose : LATIN SMALL LETTER C (U+000063), LATIN SMALL LETTER D (U+000064), ZERO WIDTH SPACE (U+00200B)

With -Uu0v2 --ascii:

 1,1c1,1
 - A > <B>CD<E> <Fg
 - -- verbose : SPACE, LATIN CAPITAL LETTER C, LATIN CAPITAL LETTER D, SPACE
 + A B>cd<E><Fg
 + -- verbose : LATIN SMALL LETTER C, LATIN SMALL LETTER D, ZERO WIDTH SPACE

And get this — the word "verbose" and the character markers get displayed using the "verbose" color 🎀 The characters used for the markers can be defined in your configuration file as "chr_cml" (the character used as marker on the left) and "chr_cmr" (the character used as marker on the right). Cute, right?

  • --markers, -m — Puts markers under each changed character in change-chunks. 🖍️

--markers is especially useful if your terminal doesn't do colors, or if you want to copy/paste the output into (ASCII) mail. See also --ascii. The markers will have the same color as added or deleted text.

This will look like (with unified diff):

 5,5c5,5
 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
 -               ▼       ▼
 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
 +               ▲       ▲

The characters used for the markers can be defined in your configuration file as "chr_old" (the character used as marker under removed characters) and "chr_new" (the character used as marker under added characters).

⚠️ If --ellipsis is also in effect and either the "chr_eli" is longer than one character or --verbose level is over 2, this option is automatically disabled. Just so you know bestie, it ghosts you.
  • --ascii, -a — Uses (colored) ASCII indicators instead of Unicode. The default indicators are Unicode characters because they stand out better. The markers will have the same color as added or deleted text.

For the vertical markers (-m) that would look like:

 5,5c5,5
 -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
 -               ^       ^
 +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539
 +               ^       ^

And for the positional indicators — ngl, I did consider using U+034e (COMBINING UPWARDS ARROW BELOW), but as most terminals are probably unable to show it due to line height changes, I did not pursue the idea. RIP that idea 💀

  • --pink, -p — Changes the default "red" for deleted text to the color closest to pink that's supported by Term::ANSIColor: "magenta". 💖 Obviously.
  • --reverse, -r — Reverses/inverts the foreground and background for the colored indicators.

And if the foreground color has "bold", it gets stripped from the new background color. Gone. Bye. ✂️

  • --swap, -s — Swaps the colors for new and old.
  • --list-colors — Lists available colors and exits.
  • --no-colors — Disables ALL colors. Super useful for redirecting the diff output into a file that's gonna be included in documentation.

This is the default if the environment variable $NO_COLOR has a true value, or if the environment variable $CLICOLOR is set to a false value. And if $CLICOLOR_FORCE is set, it overrules the default of $NO_COLOR. 👑

  • --old=color — Defines the foreground color for deleted text.
  • --new=color — Defines the foreground color for added text.
  • --bg=color — Defines the background color for changed text.
  • --index, --idx, -I — Prefixes position indicators with an index.
  [001] 5,5c5,5
  -Sat Dec 18 07:08:33 1998,I.O.D.U.,,756194433,1442539
  +Sat Dec 18 07:00:33 1993,I.O.D.U.,,756194433,1442539

And if a positive number gets passed in (--index=4 or -I 4), it displays just the chunk with that index, using the "verbose" color:

This is useful in combination with --verbose. ✨

  • --threshold=2, -t 2 — Defines the number of lines a change block may differ before the fall-back of horizontal diff to vertical diff.

So basically: if a chunk describes a change, and the number of lines in the original block has fewer or more lines than the new block, and that difference exceeds this threshold, ccdiff will fall-back to vertical diff. 🫠

  • --heuristics=n, -h n — Defines the percentage of character-changes a change block may differ before the fall-back of horizontal diff to vertical diff.

This percentage is calculated as "(characters removed + characters added) / (2 * characters unchanged))".

  • --ellipsis=n, -e n — Defines the number of characters to keep on each side of a horizontal-equal segment. The default is 0, meaning do not compress.

If set to a positive number, and the length of a segment of equal characters inside a horizontal diff is longer than twice this value, the middle part is replaced with "┈ U02508 \N{BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL}" (instead of … U02026, as HORIZONTAL ELLIPSIS does not stand out enough). 💅

With -u0me3 that would be like

 5,5c5,5
 -Sat┈07:08:33┈ 1998,I.┈539
 -        ▼        ▼
 +Sat┈07:00:33┈ 1993,I.┈539
 +        ▲        ▲

With -u0e3 -v2 like

 5,5c5,5
 -Sat↤9↦07:0↱0↰:33 199↱3↰,I.↤23↦539
 - -- verbose : DIGIT ZERO, DIGIT THREE
 +Sat↤9↦07:0↱8↰:33 199↱8↰,I.↤23↦539
 + -- verbose : DIGIT EIGHT, DIGIT EIGHT

The text used for the replaced text can be defined in your configuration file as "chr_eli" and/or "chr_eli_v". 🎀

  • --ignore-case, -i — Ignore case on comparison.
  • --ignore-all-space, -w — Ignore all white-space changes. This will set all options -b, -Z, -E, and -B. All of them. At once. ✨
  • --ignore-trailing-space, -Z — Ignore changes in trailing white-space (tabs and spaces).
  • --ignore-ws|ignore-space-change, -b — Ignore changes in horizontal white-space (tabs and spaces). This does not include white-space changes that split non-white-space, or remove white-space between two non-white-space elements.
  • --ignore-tab-expansion, -E — NYI 😭 (not yet implemented, bestie)
  • --ignore-blank-lines, -B — Just Partly Implemented (WIP) 🚧

🧚 Configuration files

So you wanna overrule the defaults that ccdiff ships with? You can set options specific for this login. The following option files are looked for, in this order:

  • $HOME/ccdiff.rc
  • $HOME/.ccdiffrc
  • $HOME/.config/ccdiff

and evaluated in that order. Any options specified in a file later in that chain will overwrite previously set options. Later wins, always. 👑

⚠️ Option files are only read and evaluated if they are not empty and not writable by others than the owner. Security check, periodt 🔒

(part 1 done, part 2 is coming, hold on 🫶)

Okay bestie, config file time 💖 The syntax is one option per line, and leading/trailing white-space just gets ignored, no big deal. If that line starts with one of the options listed below, followed by optional white-space, followed by either an = or a :, followed by optional white-space and the values — boom, the value is assigned to the option. The values no and false (case insensitive) are aliases for 0. The values yes and true are aliases to -1 (-1 being a true value).

In parens next to each one is the corresponding command-line option, iykyk. ✨

  • unified (-u) — if you prefer unified-diff over old-style diff by default, set this to the desired number of context lines:
unified : 3

The default is undefined.

  • markers (-m) —
markers : false

Defines if markers should be used under changed characters. The default is to use colors only. The -m command line option will toggle the option when set from a configuration file.

  • ascii (-a) —
ascii   : false

Defines to use ASCII markers instead of Unicode markers. The default is to use Unicode markers.

  • reverse (-r) —
reverse : false

Defines if changes are displayed as foreground-color over background-color or background-color over foreground-color. The default is false, so it will color the changes with the appropriate color (new or old) over the default background color.

  • swap (-s) —
swap    : false

Swap the colors for new and old.

  • new (--new) —
new     : green

Defines the color to be used for added text. The default is green.

The color none is also accepted and disables this color.

Any color accepted by Term::ANSIColor is allowed. Any other color will result in a warning. This option can include bold either as prefix or as suffix.

This option may also be specified as

new-color
new_color
new-colour
new_colour
  • old (--old) —
old     : red

Defines the color to be used for deleted text. The default is red.

The color none is also accepted and disables this color.

Any color accepted by Term::ANSIColor is allowed. Any other color will result in a warning. This option can include bold either as prefix or as suffix.

This option may also be specified as

old-color
old_color
old-colour
old_colour
  • bg (--bg) —
bg      : white

Defines the color to be used as background for changed text. The default is white.

The color none is also accepted and disables this color.

Any color accepted by Term::ANSIColor is allowed. Any other color will result in a warning. The bold attribute is not allowed.

This option may also be specified as

bg-color
bg_color
bg-colour
bg_colour
background
background-color
background_color
background-colour
background_colour
  • header (-H --header --HC=color --header-color=color) —
header  : 1
header  : blue_on_white

Defines if a header is displayed above the diff (default is 1), supported colors are allowed.

If the value is a valid supported color, it will show the header in that color scheme. To disable the header set it to 0 in the RC file or use --no-header as a command line argument.

  • old-label
  • new-label

Defines the tag(s) in the header for the source file(s)/stream(s).

App::ccdiff::ccdiff ($left, $right);

=>

< *STDIN  Fri Nov  7 10:14:51 2025
> *STDIN  Fri Nov  7 10:14:51 2025

App::ccdiff::ccdiff ($left, $right,
   { "old-label" => "OLD", "new-label" => "NEW" });

=>

< OLD     Fri Nov  7 10:14:51 2025
> NEW     Fri Nov  7 10:14:51 2025
  • verbose —
verbose : cyan

Defines the color to be used as color for the verbose tag. The default is cyan. This color will only be used under --verbose.

The color none is also accepted and disables this color.

Any color accepted by Term::ANSIColor is allowed. Any other color will result in a warning.

This option may also be specified as

verbose-color
verbose_color
verbose-colour
verbose_colour
  • utf8 (-U) —
utf8    : yes

Defines whether all I/O is to be interpreted as UTF-8. The default is no.

This option may also be specified as

unicode
utf
utf-8
  • index (-I) —
index   : no

Defines if the position indication for a change chunk is prefixed with an index number. The default is no. The index is 1-based.

Without this option, the position indication would be like

5,5c5,5
19,19d18
42a42,42

with this option, it would be

[001] 5,5c5,5
[002] 19,19d18
[005] 42a42,42

When this option contains a positive integer, ccdiff will only show the diff chunk with that index.

  • emacs —
emacs   : no

If this option is yes/true, calling ccdiff with just one single argument, and that argument being an existing file, the arguments will act as

$ ccdiff file~ file

if file~ exists.

  • threshold (-t) —
threshold : 2

Defines the number of lines a change block may differ before the fall-back of horizontal diff to vertical diff.

  • heuristics (-h) —
heuristics : 40

Defines the percentage of character-changes a change block may differ before the fall-back of horizontal diff to vertical diff. The default is undefined, meaning no fallback based on heuristics.

  • ellipsis (-e) —
ellipsis : 0

Defines the number of characters to keep on each side of a horizontal-equal segment. The default is 0, meaning to not compress. See also chr_eli.

  • chr_old —
chr_old : U+25BC

Defines the character used to indicate the position of removed text on the line below the text when option -m is in effect.

  • chr_new —
chr_new : U+25B2

Defines the character used to indicate the position of added text on the line below the text when option -m is in effect.

  • chr_cml —
chr_cml : U+21B1

Defines the character used to indicate the starting position of changed text in a line when verbose level is 3 and up.

  • chr_cmr —
chr_cmr : U+21B0

Defines the character used to indicate the ending position of changed text in a line when verbose level is 3 and up.

  • chr_eli —
chr_eli : U+2508

Defines the character used to indicate omitted text in large unchanged text when --ellipsis/-e is in effect.

This character is not equally well visible on all terminals or in all fonts, so you might want to change it to something that stands out better in your environment. Possible suggestions:

… U+2026 HORIZONTAL ELLIPSIS
‴ U+2034 TRIPLE PRIME
‷ U+2037 REVERSED TRIPLE PRIME
↔ U+2194 LEFT RIGHT ARROW
↭ U+21ad LEFT RIGHT WAVE ARROW
↮ U+21ae LEFT RIGHT ARROW WITH STROKE
↹ U+21b9 LEFTWARDS ARROW TO BAR OVER RIGHTWARDS ARROW TO BAR
⇄ U+21c4 RIGHTWARDS ARROW OVER LEFTWARDS ARROW
⇆ U+21c6 LEFTWARDS ARROW OVER RIGHTWARDS ARROW
⇎ U+21ce LEFT RIGHT DOUBLE ARROW WITH STROKE
⇔ U+21d4 LEFT RIGHT DOUBLE ARROW
⇹ U+21f9 LEFT RIGHT ARROW WITH VERTICAL STROKE
⇼ U+21fc LEFT RIGHT ARROW WITH DOUBLE VERTICAL STROKE
⇿ U+21ff LEFT RIGHT OPEN-HEADED ARROW
≋ U+224b TRIPLE TILDE
┄ U+2504 BOX DRAWINGS LIGHT TRIPLE DASH HORIZONTAL
┅ U+2505 BOX DRAWINGS HEAVY TRIPLE DASH HORIZONTAL
┈ U+2508 BOX DRAWINGS LIGHT QUADRUPLE DASH HORIZONTAL
┉ U+2509 BOX DRAWINGS HEAVY QUADRUPLE DASH HORIZONTAL
⧻ U+29fb TRIPLE PLUS
⬌ U+2b0c LEFT RIGHT BLACK ARROW
  • chr_eli_v —
chr_eli_v : U+21A4U+21A6

When using --ellipsis with --verbose level 2 or up, the single character indicator will be replaced with this character. If it is 2 characters wide, the length of the compressed part is put between the characters.

A suggested alternative might be U+21E4U+21E5

  • iwbZusePP — as Algorithm::Diff::XS is fast but is not 100% drop-in compliant with Algorithm::Diff and options -i, -w, -b, and -Z are likely to not work in the XS version, this option allows automatic switching to the slower version if any of these options is selected.

🌈 Git integration 🌈

You can use ccdiff to show diffs in git. It may work like this:

$ git config --global diff.tool ccdiff
$ git config --global difftool.prompt false
$ git config --global difftool.ccdiff.cmd 'ccdiff --utf-8 -u -r $LOCAL $REMOTE'
$ git difftool SHA~..SHA
$ wget https://github.com/Tux/App-ccdiff/raw/master/Files/git-ccdiff \
   -O ~/bin/git-ccdiff
$ perl -pi -e 's{/pro/bin/perl}{/usr/bin/env perl}' ~/bin/git-ccdiff
$ chmod 755 ~/bin/git-ccdiff
$ git ccdiff SHA

Of course you can use curl instead of wget and you can choose your own (fixed) path to perl instead of using /usr/bin/env.

From then on you can do

$ git ccdiff
$ git ccdiff 5c5a39f2

💀 CAVEATS 💀

Due to the implementation, where both sides of the comparison are completely kept in memory, this tool might not be able to deal with (very) large datasets. Bestie, we're holding it all in RAM, so like… be mindful. 😭

🦋 Speed 🦋

There are situations where Algorithm::Diff takes considerably more time compared to e.g. GNU diff. Installing Algorithm::Diff::XS will make ccdiff a lot faster. ccdiff will choose Algorithm::Diff::XS if available.

Note however that options like -i, -w, -b, and -Z are likely to be a no-op in Algorithm::Diff::XS, as that has not been implemented and it is rather unlikely it will be. Choose --dc=pp then. If you want this switch always, set iwbZusePP = 1 in one of your Configuration files.

👀 SEE ALSO 👀

Algorithm::Diff::XS, Algorithm::Diff, Text::Diff

👑 AUTHOR 👑

H.Merijn Brand

Copyright (C) 2018-2026 H.Merijn Brand.  All rights reserved.

This library is free software; you can redistribute and/or modify it under the same terms as The Artistic License 2.0.

And that's the whole page, bestie!! 🫶 This iconic little number is perl v5.42.0, dated 2026-01-31, and it lives in the CCDIFF(1) manual section. Go forth and diff, you absolute main character. 💅✨

📦 where this page comes from