File: colordiff.xml

package info (click to toggle)
colordiff 1.0.18-1
  • links: PTS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 176 kB
  • ctags: 10
  • sloc: perl: 455; xml: 201; makefile: 90; sh: 38
file content (198 lines) | stat: -rw-r--r-- 6,303 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
<?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: -->