<?xml version="1.0" encoding="utf8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
 "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd" [
 <!ENTITY diff "<command>diff</command>">
 <!ENTITY colordiff "<application>colordiff</application>">
]>

<!-- mostly borrowed from bogofilter's bogofilter.xml file, originally
     by eric raymond -->

<refentry id='colordiff.1'>
  <refentryinfo>
    <authorgroup>
        <author>
            <firstname>Dave</firstname>
            <surname>Ewart</surname>
            <contrib>colordiff author and Debian packager</contrib>
        </author>
        <author>
            <firstname>Graham</firstname>
            <surname>Wilson</surname>
            <contrib>Manual page and XML source author</contrib>
        </author>
        <author>
            <firstname>Colin</firstname>
            <surname>Tuckley</surname>
            <contrib>Debian package sponsor</contrib>
        </author>
    </authorgroup>
    <productname>colordiff</productname>
  </refentryinfo>
  <refmeta>
    <refentrytitle>colordiff</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="manual">User Commands</refmiscinfo>
  </refmeta>

  <refnamediv id='name'>
    <refname>colordiff</refname>
    <refpurpose>a tool to colorize &diff; output</refpurpose>
  </refnamediv>

<refsynopsisdiv id='synopsis'>
  <cmdsynopsis>
    <command>colordiff</command>
    <arg choice='opt'><replaceable>diff options</replaceable></arg>
    <arg choice='opt'><replaceable>colordiff options</replaceable></arg>
    <arg choice='req'><replaceable>file1</replaceable></arg>
    <arg choice='req'><replaceable>file2</replaceable></arg>
  </cmdsynopsis>
</refsynopsisdiv>

<refsect1 id='description'><title>Description</title>

<para>&colordiff; is a wrapper for &diff; and produces the same output as
&diff; but with coloured syntax highlighting at the command line to improve
readability. The output is similar to how a &diff;-generated patch might appear
in <application>Vim</application> or <application>Emacs</application> with the
appropriate syntax highlighting options enabled. The colour schemes can be
read from a central configuration file or from a local user
<filename>~/.colordiffrc</filename> file.</para>

<para>&colordiff; makes use of ANSI colours and as such will only work when
ANSI colours can be used - typical examples are xterms and Eterms, as well as
console sessions.</para>

<para>&colordiff; has been tested on various flavours of Linux and under
OpenBSD, but should be broadly portable to other systems.</para>

</refsect1>

<refsect1 id="usage"><title>Usage</title>

<para>Use &colordiff; wherever you would normally use &diff;, or instead
pipe output to &colordiff;:</para>

<para>For example:

<screen>
$ colordiff file1 file2
$ diff -u file1 file2 | colordiff
</screen>

</para>

<para>You can pipe the output to 'less', using the '-R' option (some systems or
terminal types may get better results using '-r' instead), which keeps
the colour escape sequences, otherwise displayed incorrectly or discarded by
'less':

<screen>
$ diff -u file1 file2 | colordiff | less -R
</screen>

</para>

<para>If you want to force disable colour escape sequences (for example
pipe the output to <command>patch</command>), you can use option 
'--color=no' to do so:

<screen>
$ diff -u file1 file2 | colordiff --color=no | patch -p0 -d another-working-dir
</screen>

</para>

<para>If you have <command>wdiff</command> installed, colordiff will correctly
colourise the added and removed text, provided that the '-n' option is given to
<command>wdiff</command>:

<screen>
$ wdiff -n file1 file2 | colordiff
</screen>

</para>

<para>You may find it useful to make &diff; automatically call
<command>colordiff</command>. Add the following line to
<filename>~/.bashrc</filename> (or equivalent):

<screen>
alias diff=colordiff
</screen>

</para>

<para>Any options passed to &colordiff; are passed through to &diff; except for
the colordiff-specific option 'difftype', e.g.</para>

<screen>
colordiff --difftype=debdiff file1 file2
</screen>

<para>Valid values for 'difftype' are: diff, diffc, diffu, diffy, wdiff, debdiff;
these correspond to plain diffs, context diffs, unified diffs, side-by-side
diffs, wdiff output and debdiff output respectively.  Use these overrides when
colordiff is not able to determine the diff-type automatically.</para>

<para>Alternatively, a construct such as 'cvs diff SOMETHING | colordiff' can be
included in <filename>~/.bashrc</filename> as follows:

<screen>
function cvsdiff () { cvs diff $@ | colordiff; }
</screen>

</para>

<para>Or, combining the idea above using 'less':

<screen>
function cvsdiff () { cvs diff $@ | colordiff |less -R; }
</screen>

</para>

<para>Note that the function name, cvsdiff, can be customized.</para>

<para>By default colordiff returns the exit code of the underlying diff
invocation (if there is one), but there are some circumstances where it is
useful to force colordiff's exit code to be zero: to do this use the option
'--fakeexitcode':

<screen>
colordiff --fakeexitcode ...
</screen>

</para>

</refsect1>

<refsect1 id='files'><title>Files</title>

<variablelist><varlistentry>
  <term><filename>/etc/colordiffrc</filename></term>
  <listitem><para>Central configuration file. User-specific settings can be
  enabled by copying this file to <filename>~/.colordiffrc</filename> and
  making the appropriate changes.</para></listitem></varlistentry>
  <varlistentry><term><filename>colordiffrc-lightbg</filename></term>
  <listitem><para>Alternate configuration template for use with terminals having
  light backgrounds.  Copy this to /etc/colordiffrc or ~/.colordiffrc and
  customize.</para></listitem></varlistentry>
  <varlistentry><term><filename>colordiffrc-gitdiff</filename></term>
  <listitem><para>Alternate configuration template for use with terminals having
  dark backgrounds, with colour defaults set to match the output of 'git diff'.
  Copy this to /etc/colordiffrc or ~/.colordiffrc and customize.</para></listitem>
</varlistentry></variablelist>

</refsect1>

<refsect1 id='bugs'><title>Bugs</title>

<para>Bug reports and suggestions/patches to <email>davee@sungate.co.uk</email>
please.</para>

</refsect1>

</refentry>
<!-- vim:set ts=2 sw=2 et: -->