annotate kdiff3/doc/en/index.docbook @ 66:efe33e938730

0.9.86

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kdiff3 "<application>KDiff3</application>">
  <!ENTITY kappname "&kdiff3;">
  <!ENTITY package "kdeextragear-1">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kdiff3; Handbook</title>

<authorgroup>
<author>
<!--<personname>-->
<firstname>Joachim</firstname>
<surname>Eibl</surname>
<!--</personname>-->
<affiliation><address>
   <email>joachim.eibl at gmx.de</email>
</address></affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2002-2004</year>
<holder>Joachim Eibl</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (YYYY-MM-DD) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>2004-05-29</date>
<releaseinfo>0.9.84</releaseinfo>


<abstract>
<para></para>
<para>
   &kdiff3; is a file and directory diff and merge tool which
<itemizedlist>
<listitem><para>compares and merges two or three text input files or directories,</para></listitem>
<listitem><para>shows the differences line by line and character by character(!),</para></listitem>
<listitem><para>provides an automatic merge-facility,</para></listitem>
<listitem><para>has an editor for comfortable solving of merge-conflicts,</para></listitem>
<listitem><para>provides networktransparency via KIO,</para></listitem>
<listitem><para>has options to highlight or hide changes in white-space or comments.</para></listitem>
</itemizedlist>
</para><para>
   This document describes KDiff3-version 0.9.84.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeextragear</keyword>
<keyword>kdiff3</keyword>
<keyword>diff</keyword>
<keyword>merge</keyword>
<keyword>CVS</keyword>
<keyword>triplediff</keyword>
<keyword>compare</keyword>
<keyword>files</keyword>
<keyword>directories</keyword>
<keyword>version control</keyword>
<keyword>three-way-merge</keyword>
<keyword>in-line-differences</keyword>
<keyword>synchronise</keyword>
<keyword>kpart</keyword>
<keyword>kio</keyword>
<keyword>networktransparent</keyword>
<keyword>editor</keyword>
<keyword>white space</keyword>
<keyword>comments</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction"><title>Introduction</title>
<sect1 id="why"><title>Yet Another Diff Frontend?</title>
<para>
Several graphical diff tools exist. Why choose KDiff3? Let me say, why I wrote it.
</para><para>
KDiff3 started because I had to do a difficult merge. Merging is necessary when several
people work on the same files in a project. A merge can be somewhat automated, when the
merge-tool not only has the new modified files (called "branches"), but also the original file
(called "base"). The merge tool will automatically choose any modification that was only
done in one branch. When several contributors change the same lines, then the merge tool
detects a conflict which must be solved manually.
</para><para>
The merge then was difficult because one contributor had changed many things and corrected
the indentation in many places. Another contributor also had changed much text in the same file,
which resulted in several merge conflicts.
</para><para>
The tool I used then, only showed the changed lines, but not what had changed within these
lines. And there was no information about where only the indentation was changed. The merge
was a little nightmare.
</para><para>
So this was the start. The first version could show differences within a line and showed white space differences.
Later many other features were added to increase the usefulness.
</para><para>
For example if you want to compare some text quickly, then you can copy it to the clipboard and
paste it into either diff window.
</para><para>
A feature that required a big effort was the directory comparison and merge facility, which turned
the program almost into a full file browser.
</para><para>
I hope KDiff3 works for you too. Have fun!
</para><para>
Joachim Eibl (2003)
</para>
</sect1>

<sect1 id="screenshots"><title>Screenshots and Features</title>
<para>This screenshot shows the difference between two text files</para>
<para>(Using an early version of KDiff3):</para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
</mediaobject></screenshot>

<para>
   3-way-merging is fully supported. This is useful if two people change code independently.
   The original file (the base) is used to help KDiff3 to automatically select the correct
   changes.
   The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get.
   You can even edit the output.
   This screenshot shows three input files being merged:
</para><para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
</para>

<para id="dirmergebigscreenshot">KDiff3 also helps you to compare and merge complete directories.
This screenshot shows KDiff3 during a directory merge:
</para><para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="dirmergebig.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
</para>
</sect1>

<sect1 id="features"><title>More Features</title>
<sect2><title> Line-By-Line And Char-By-Char Diff-Viewer</title>
<para>By using the possiblities of a graphical color display KDiff3 shows
   exactly what the difference is. When you have to do many code-reviews, you will like this.
</para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="letter_by_letter.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
</sect2>

<sect2><title> See White-Space Differences At One Glance</title>
<para>Spaces and tabs that differ appear visibly. When lines differ only
   in  the  amount of white space this can be seen at one look in the summary
   column on the left side. (No more worries when people change the indentation.)
</para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="white_space.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
</sect2>

<sect2><title> Triple-Diff</title>
<para> Analyze three files and see where they differ.
</para><para>
   The left/middle/right windows are named A/B/C and have the blue/green/magenta
   color respectively.
</para><para>
   If one file is the same and one file is different on a line then the
   color   shows which file is different. The red color means that both other
   files  are different.
</para>
<screenshot><mediaobject>
   <imageobject><imagedata fileref="triple_diff.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
</sect2>

<sect2><title> Comfortable Merge Of Two Or Three Input Files</title>
<para> KDiff3 can be used to merge two or three input files and automatically
   merges as much as possible. The result is presented in an editable window
   where most conflicts can be solved with a single mouseclick: Select the
   buttons  A/B/C from the button-bar to select the source that should be used.
   You can  also select more than one source. Since this output window is an
   editor even  conflicts which need further corrections can be solved here without
   requiring  another tool.
</para>
</sect2>

<sect2><title>And ...</title>
<itemizedlist>
   <listitem><para>Fast navigation via buttons.</para></listitem>
   <listitem><para>A mouse-click into a summary column sync's all windows to show the same position.</para></listitem>
   <listitem><para>Select and copy from any window and paste into the merge result window.</para></listitem>
   <listitem><para>Overview column that shows where the changes and conflicts are.</para></listitem>
   <listitem><para>The colors are adjustable to your specific preferences.</para></listitem>
   <listitem><para>Adjustable Tab size.</para></listitem>
   <listitem><para>Option to insert spaces instead of tabs.</para></listitem>
   <listitem><para>Open files comfortably via dialog or specify files on the command line.</para></listitem>
   <listitem><para>Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)</para></listitem>
   <listitem><para>Show the line numbers for each line. </para></listitem>
   <listitem><para>Paste clipboard or drag text into a diff input window.</para></listitem>
   <listitem><para>Networktransparency via KIO.</para></listitem>
   <listitem><para>Can be used as diff-viewer in KDevelop 3.</para></listitem>
   <listitem><para>Word-wrap for long lines.</para></listitem>
   <listitem><para>...</para></listitem>
</itemizedlist>
</sect2>
</sect1>
</chapter>

<chapter id="documentation"><title>Documentation of File Comparison And Merge</title>

<sect1 id="commandline"><title>Command-Line Options</title>

<sect2><title>Comparing 2 files: </title>
<screen>
   <command>kdiff3</command> <replaceable>file1 file2</replaceable>
</screen>
</sect2>

<sect2><title>Merging 2 files: </title>
<screen>
   <command>kdiff3</command> <replaceable>file1 file2</replaceable> -m
   <command>kdiff3</command> <replaceable>file1 file2</replaceable> -o <replaceable>outputfile</replaceable>
</screen>
</sect2>

<sect2><title>Comparing 3 files: </title>
<screen>
   <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable>
</screen>
</sect2>

<sect2><title>Merging 3 files: </title>
<screen>
   <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -m
   <command>kdiff3</command> <replaceable>file1 file2 file3</replaceable> -o <replaceable>outputfile</replaceable>
</screen>
<para>
   Note that <replaceable>file1</replaceable> will be treated as
   base of <replaceable>file2</replaceable> and
   <replaceable>file3</replaceable>.
</para>
</sect2>

<sect2><title>Special case: Files with the same name </title>
<para>
If all files have the same name but are in different directories, you can
reduce typework by specifying the filename only for the first file. E.g.:
</para>
<screen>
   <command>kdiff3</command> <replaceable>dir1/filename dir2 dir3</replaceable>
</screen>
</sect2>

<sect2><title>Commandline for starting a directory comparison or merge: </title>
<para>This is very similar, but now it's about directories.</para>
<screen>
   <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
   <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
   <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
   <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
</screen>
<para>For directory comparison and merge you can continue to read <link linkend="dirmerge">here</link>.</para>
</sect2>

<sect2><title>For more information on command line options use: </title>
<screen>
   <command>kdiff3</command> --help
Options:
  -m, --merge               Merge the input.
  -b, --base file           Explicit base file. For compatibility with certain tools.
  -o, --output file         Output file. Implies -m. E.g.: -o newfile.txt
  --out file                Output file, again. (For compatibility with certain tools.)
  --auto                    No GUI if all conflicts are auto-solvable. (Needs -o file)
  --qall                    Don't solve conflicts automatically. (For compatibility...)
  --L1 alias1               Visible name replacement for input file 1 (base).
  --L2 alias2               Visible name replacement for input file 2.
  --L3 alias3               Visible name replacement for input file 3.
  -L, --fname alias         Alternative visible name replacement. Supply this once for every input.
  -u                        Has no effect. For compatibility with certain tools.
</screen>
</sect2>

</sect1>

<sect1 id="opendialog"><title>Open-Dialog</title>
<para>
   Since many input files must be selectable, the program has a special open dialog:
</para>
<screenshot><mediaobject>
<imageobject><imagedata fileref="open_dialog.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
<para>
   The open dialog allows to edit the filenames by hand, selecting a file
   via  the file-browser ("File...") or allows to choose recent files from
   the drop-down lists. If you open the dialog again, then the current names
   still remain there. The third input file is not required. If the
   entry   for "C" remains empty, then only a two file diff analysis will be
   done.
</para><para>
   You can also select a directory via "Dir...". If for A a directory is specified
   then a directory-comparison/merge starts. If A specifies a file but B, C or
   the output specify a directory, then KDiff3 uses the filename from A in the
   specified directories.
</para><para>
   If "Merge" is selected, then the "Output"-line becomes editable. But it
   is not required to specify the output filename immediately. You can also
   postpone this until saving.
</para><para>
   The "Configure..."-button opens the options-dialog, so that you can set
   the options before running the analysis.
</para>
</sect1>

<sect1 id="pasteinput"><title>Paste and Drop Input</title>
<para>
   Sometimes you want to compare parts of a text that is not an own file. KDiff3 also
   allows you to paste text from the clipboard into the diff input window that has the focus.
   The diff analysis happens immediately then.
   In the open dialog you need not specify files then, but just close it via "Cancel".
</para><para>
   You can also use drag and drop: Drag a file from a file manager
   or selected text from an editor and drop it onto a diff input window.
</para><para>
   What's the idea? Sometimes a file contains two similar functions, but checking how similar
   they really are is a big effort if you first must create two files and then load them. Now
   you can simply copy, paste and compare the relevant sections.
</para><para>
   Note: Currently you can't drag anything from KDiff3. Only dropping in the diff input
   is supported.
</para><para>
   Warning: Some editors still interpret the drag and drop into another program like cut
   (instead of copy) and paste. Your original data might be lost then.
</para>
</sect1>

<sect1 id="interpretinginformation"><title>Interpreting The Information In The Input Windows</title>
<screenshot><mediaobject>
<imageobject><imagedata fileref="screenshot_diff.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
<para>
   At the top of each text window is its "info line". The info lines of
   the   input windows contain a letter "A", "B" or "C", the filename and the
   line   number of the first visible line in the window. (Note that window
   "C" is  optional.) Each info line appears in a different color. (If the paths
   are too long to fit, then you can move the mouse onto the info line and
   a  tooltip will show the complete name.)
</para><para>
   The three input windows are assigned the letters "A", "B" and "C".
   "A"   has  color blue, "B" has green and "C" has magenta. (These are the
   defaults,   but  can be changed in the Settings-Menu.)
</para><para>
   When a difference is detected then the color shows which input file
   differs.   When both other input files differ then the color used to express
   this is   red by default ("Conflict color" in the Settings).
   This colorscheme is especially useful in the case of three input files, which will be
   seen in the next section (<link linkend="merging">Merging</link>).
</para><para>
   Left of each text is the "summary column". If differences occurred on a
   line then the summary column shows the respective color. For a white-space-only
   difference the summary is chequered. For programming languages where white
   space is not so important this is useful to see at one glance if anything
   of importance was modified. (In C/C++ white space is only interesting within
   strings, comments, for the preprocessor, and some only very esoteric situations.)
</para><para>
   The vertical line separating the summary column and the text is interrupted
   if the input file had no lines there. When word-wrap is enabled then this vertical 
   line appears dotted for wrapped lines.
</para><para>
   On the right side a "overview"-column is visible left of the vertical scrollbar.
   It shows the compressed summary column of input "A". All the differences
   and conflicts are visible at one glance. When only two input windows are
   used, then all differences appear red here because every difference is
   also   a conflict. A black rectangle frames the visible part of the inputs.
   For  very long input files, when the number of input lines is bigger than
   the height of the overview column in pixels, then several input lines share
   one overview line. A conflict then has top priority over simple differences,
   which have priority over no change, so that no difference or conflict is
   lost here.  By clicking into this overview column the corresponding text
   will be shown.
</para>
</sect1>


<sect1 id="merging"><title>Merging And The Merge Output Editor Window</title>
<screenshot><mediaobject>
<imageobject><imagedata fileref="screenshot_merge.png" format="PNG"/></imageobject>
</mediaobject></screenshot>
<para>
   The merge output editor window (below the diff input windows) also has an info line at the top showing "Output:", the
   filename   and "[Modified]" if you edited something. Usually it will contain
   some text  through the automatic merge facilities, but often it will also
   contain conflicts.
</para><para>
   !!! Saving is disabled until all conflicts are resolved !!! (Use the "Go
   to prev/next unsolved conflicts"-buttons to find the remaining conflicts.)
</para><para>
   With only two input files every difference is also a conflict that must
   be solved manually.
</para><para>
   With three input files the first file is treated as base, while the
   second   and third input files contain modifications. When at any line only
   either   input B or input C have changed but not both then the changed source
   will   automatically be selected. Only when B and C have changed on the same
   lines,   then the tool detects a conflict that must be solved manually.
   When B and C are the same, but not the same as A, then C is selected.
</para><para>
   The merge output editor window also has a summary column on the left. It shows the
   letter of the input from which a line was selected or nothing if all three
   sources where equal on a line. For conflicts it shows a questionmark "?"
   and the line shows "&lt;Merge Conflict&gt;", all in red. Because solving
   conflicts  line by line would take very long, the lines are grouped into
   groups that  have the same difference and conflict characteristics.
   But only-white-space-conflicts are separated from non-white-space-conflicts
   in order to ease the merging of files were the indentation changed for many
   lines.
</para><para>
   When clicking into  the summary column with the left mouse button in either
   window then the group belonging to that line will be selected in all windows
   and the beginning of that group will be shown. (This might involve an automatic
   position jump in the windows if the beginning of a group is not visible.)
   This group then becomes the "current group". It is highlighted with the
   "Current range (diff) background color" and
   a black bar appears on the left side of the text.
</para><para>
   Note the input selector buttons containing the letters "A", "B" and
   "C"   in the button bar below the menu bar. When clicking on either input
   selector   button, the lines from that input will be added at the end of the
   selected   group if that group didn't contain that source before. Otherwise
   the lines   from that input will be removed.
</para><para>
   Besides, you can directly edit any line. The summary column will show "m"
   for every line that was modified.
</para><para>
   Sometimes, when a line is removed either by automatic merge or by editing
   and no other lines remain in that group, then the text &lt;No src line&gt;
   will appear in that line. This is just a placeholder for the group for
   when  you might change your mind and select some source again. This text won't
   appear in the saved file or in any selections you want to copy and paste.
</para><para>
   The text "&lt;Merge Conflict&gt;" will appear in the clipboard if you
   copy and   paste some text containing such a line. But still be careful to
   do so.
</para><para>
   The normal merge will start by solving simple conflicts automatically.
   But the "Merge"-menu provides some actions for other common needs.
   If you have to select the same source for most conflicts, then you can
   choose "A", "B" or "C" everywhere, or only for the remaining unsolved
   conflicts, or for unsolved whitespace conflicts. If you want to decide every
   single delta yourself, you can "Set deltas to conflicts". Or if you want to
   return to the automatic choices of KDiff3 then select
   "Automatically solve simple conflicts". KDiff3 then restarts the merge.
   For actions that change your previous modifications KDiff3 will ask for your
   confirmation before proceeding.
</para><para>
   Note: When choosing either source for unsolved whitespace conflicts and
   the options "Ignore Numbers" or "Ignore C/C++ Comments" are used then changes in
   numbers or comments will be treated like whitespace too.
</para>
</sect1>

<sect1 id="navigation"><title>Navigation And Editing</title>
<para>
   Much navigation will be done with the scroll bars and the mouse but
   you  can also navigate with the keys. If you click into either window then
   you  can use the cursor buttons left, right, up, down, page up, page down,
   home,  end, ctrl-home, ctrl-end as you would in other programs. The overview-column
   next to the vertical scroll bar of the input files can also be used  for
   navigating by clicking into it.
</para><para>
   You can also use the wheel mouse to scroll up and down.
</para><para>
   In the merge output editor you can also use the other keys for editing.
   You can toggle between insert and overwrite mode with the insert key. (Default
   is insert-mode.)
</para><para>
   A left-mouse-button-click into any summary column will synchronise all
   windows to show the beginning of the same group of lines (as explained
   in section <link linkend="merging">"Merging"</link>).
</para><para>
   The button bar also contains seven navigation buttons with which you can
   jump to the current/first/last difference, to the next/previous difference
   (ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup),
   or to the next/previous unsolved conflict. Note that for KDiff3 a "conflict"
   that was not automatically solved at the start of the merge stays a "conflict"
   even if it is solved. Hence the necessity to distinguish "unsolved conflicts".
</para><para>
   There also is a button "Automatically go to next unsolved conflict after
   source selection" (Auto-Advance). If you enable this, then, when one source
   is selected, then KDiff3 will jump to and select the next unsolved conflict
   automatically. This can help when you always want to choose one source only.
   When you need both sources, or you want to edit after selecting, then you
   probably want to switch this off. Before proceeding to the next unsolved conflict
   KDiff3 shows you the effect of your choice for a short time. This delay is
   adjustable in the Diff- &amp; Merge-Settings: You can
   specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint:
   Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts
   Ctrl-1/2/3 to select A/B/C for many conflicts.
</para>
</sect1>

<sect1 id="selections"><title>Select, Copy And Paste</title>
<para>
   The input windows don't show a cursor, so selections must be made
   with   the mouse by clicking with the left mouse button at the start, holding
   down   the mousebutton and moving to the end, where you release the mouse
   button   again. You can also select a word by double clicking it. In the merge
   output   editor you can also select via the keyboard by holding the "shift"-button
   and navigation with the cursor keys.
</para><para>
   To copy to the clipboard you must press the "Copy"-button (Ctrl-C or Ctrl-Insert).
   But   there exists an option "Auto Copy Selection". If this is enabled,
   then  whatever   you select is copied immediately and you don't need to explicitely
   copy. But pay attention when using this because the contents of the clipboard
   might   then be destroyed accidentally.
</para><para>
   "Cut" (Ctrl-X or Shift-Delete) copies to the clipboard and deletes the
   selected text and   "Paste" (Ctrl-V or Shift-Insert) inserts the text in
   the clipboard at the cursorposition  or over the current selection.
</para>
</sect1>

<sect1 id="saving"><title>Saving</title>
<para>
   Saving will only be allowed, when all conflicts were solved. If the file
   already exists and the "Backup files"-option is enabled then the existing
   file will be renamed with an ".orig"-extension, but if such a file exists
   it will be deleted. When you exit or start another diff-analysis and data
   wasn't saved yet, then KDiff3 will ask if you want to save, cancel or proceed
   without saving. (KDiff3 does not catch any signals. So if you "kill" KDiff3
   then your data will be lost.)
</para><para>
   Line endings are saved according to the normal method on the underlying
   operating system. For Unices each line ends with an linefeed-character "\n",
   while for Win32-based systems each line ends with a carriage-return + a linefeed
   "\r\n". KDiff3 does not preserve the line-endings of the input files, which
   also means that you shouldn't use KDiff3 with binary files.
</para>
</sect1>

<sect1 id="find"><title>Finding Strings</title>
<para>
   You can search for a string in any text-window of KDiff3. The "Find ..."-command
   (Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string
   to search for. You can also select the windows which should be searched.
   Searching will always start at the top. Use the "Find Next"-command (F3)
   to proceed to the next occurance. If you select to search several windows then the first
   window will be searched from top to bottom before the search starts in the next
   window at the top again, etc.
</para>
</sect1>


<sect1 id="options"><title>Options</title>
<para>
   Options and the recent-file-list will be saved when you exit the program,
   and reloaded when you start it. (Menu Settings->Configure KDiff3 ...)
</para>
<sect2><title>Font</title>
<para>
   Select a fixed width font. (On some systems this dialog will also
   present    variable width fonts, but you should not use them.)
</para>
<variablelist>
   <varlistentry><term><emphasis>Italic Font for Deltas:</emphasis></term><listitem><para> If you select this, then text differences
       will be drawn with the italic version of the selected font. If the font
       doesn't  support italic, then this does nothing.</para>
   </listitem></varlistentry>
</variablelist>
</sect2>

<sect2><title>Colors</title>
<variablelist>
   <varlistentry><term><emphasis>Foreground color:</emphasis></term><listitem><para> Usually black. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Background color:</emphasis></term><listitem><para> Usually white. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Diff Background color:</emphasis></term><listitem><para> Usually light gray. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Color A:</emphasis></term><listitem><para> Usually dark blue. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Color B:</emphasis></term><listitem><para> Usually dark green. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Color C:</emphasis></term><listitem><para> Usually dark magenta. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Conflict Color:</emphasis></term><listitem><para> Usually red.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Current range background color:</emphasis></term><listitem><para> Usually light yellow.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Current range diff background color:</emphasis></term><listitem><para> Usually dark yellow.</para></listitem></varlistentry>
</variablelist>
<para>
   On systems with only 16 or 256 colors some colors are not available in pure
   form. On such systems the "Defaults"-button will choose a pure color.
</para>
</sect2>

<sect2><title>Editor Settings</title>
<variablelist>
   <varlistentry><term><emphasis>Tab inserts spaces:</emphasis></term><listitem><para> If this is disabled and you press the
      tabulator key,   a tab-character is inserted, otherwise the appropriate
      amount  of characters   is inserted.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>   Tab size:</emphasis></term><listitem><para> Can be adjusted for your specific needs. Default is 8. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>   Auto indentation:</emphasis></term><listitem><para> When pressing Enter or Return the indentation
      of the previous  line is used for the new line. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>   Auto copy selection:</emphasis></term><listitem><para> Every selection is immediately copied
      to the clipboard   when active and you needn't explicitely copy it. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>   Line end style:</emphasis></term><listitem><para> When saving you can select what line 
      end style you prefer. The default setting is the common choice for the used operating system. </para></listitem></varlistentry>
   <varlistentry><term><emphasis>   Use locale encoding:</emphasis></term><listitem><para> For displaying foreign characters.
      Try changing this if some characters of your language aren't displayed correctly. </para></listitem></varlistentry>
</variablelist>
</sect2>

<sect2><title>Diff &amp; Merge Settings</title>
<para>
   When comparing files, KDiff3 first it tries to match lines that are equal
   in all input files. Only during this step it might ignore white space. The
   second step compares each line. In this step white space will not be ignored.
   Also during the merge white space will not be ignored.
</para>

<variablelist>
   <varlistentry><term><emphasis>Preserve Carriage Return:</emphasis></term><listitem><para> Some editors (on some systems) save
      carriage return '\r' and linefeed '\n'-characters at the end of line, while
      others will only save the linefeed '\n'. Usually KDiff3 ignores the carriage
      return, but then files that don't have equal sizes, look equal in side by
      side comparison. When this option is on, then the carriage return characters
      are made visible but are treated as white space. This option must be off
      during a merge. Default is off.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Ignore numbers:</emphasis></term><listitem><para> Default is off. Number characters ('0'-'9', '.', '-')
      will be ignored  in the first  part of the analysis in which the line matching is
      done. In the result the differences will be shown nevertheless, but they are treated
      as white space.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Ignore C/C++ comments:</emphasis></term><listitem><para> Default is off.
      Changes in comments will be treated like changes in white space.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Ignore case:</emphasis></term><listitem><para>  Default is off. 
      Case-differences of characters (like 'A' vs. 'a') will be treated like changes in white space.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para>
   See <link linkend="preprocessors">next section</link>.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para>
   See <link linkend="preprocessors">next section</link>.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Try Hard:</emphasis></term><listitem><para>
      Try hard to find an even smaller delta. (Default is on.) This will probably
      be effective for complicated and big files. And slow for very big files.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Auto Advance Delay (ms):</emphasis></term><listitem><para> When in auto-advance-mode this setting specifies
      how long to show the result of the selection before jumping to the next unsolved
      conflict.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>White space 2/3-file merge default:</emphasis></term><listitem><para>
      Automatically solve all white-space conflict by choosing the specified file.
      (Default is manual choice.) Useful if white-space really isn't important in many files.
      If you need this only occasionally better use "Choose A/B/C For All Unsolved Whitespace Conflicts"
      in the merge menu. Note that if you enable either "Ignore numbers" or "Ignore C/C++ comments"
      then this auto-choice also applies for conflicts in numbers or comments.
   </para></listitem></varlistentry>
</variablelist>

</sect2>

<sect2><title>Directory Merge</title>
<para>
   These options are concerned with scanning the directory and handling the
   merge: See the <link linkend="dirmergeoptions">Directory Comparison/Merge
   Docs</link> for details.
</para><para>
Yet there is one option here that is also relevant for saving single files:
</para>
<variablelist>
   <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> When a file is saved and an older version already
      exists, then the original version will be renamed with an ".orig" extension.
      If an old backup file with ".orig" extension already exists then this will
      be deleted without backup.
   </para></listitem></varlistentry>
</variablelist>
</sect2>

<sect2><title>Miscellaneous</title>
<para>(These options and actions are available in menus or the buttonbar.)</para>
<variablelist>
  <varlistentry><term><emphasis>Show line numbers:</emphasis></term><listitem><para> You can select if line numbers should be
     shown for the input files.</para></listitem></varlistentry>
  <varlistentry><term><emphasis>Show space and tabulator characters for differences:</emphasis></term><listitem><para> Sometimes
     the visible spaces and tabs are disturbing. You can turn this off.</para></listitem></varlistentry>
  <varlistentry><term><emphasis>Show white space:</emphasis></term><listitem><para> Turn this off to suppress
      any highlighting of white-space-only changes in the text or overview-columns.
      (Note that this also applies to changes in numbers or comments if the options "Ignore numbers"
      or "Ignore C/C++ comments" are active.)</para></listitem></varlistentry>
  <varlistentry><term><emphasis>Overview options:</emphasis></term><listitem><para>
     These choices are only available when you compare three files. In normal mode all
     differences are shown in one color-coded overview-column. But sometimes you are  
     especially interested in the differences between only two of these three files.
     Selecting "A vs. B", "A vs. C" or "B vs. C"-overview will show a second overview 
     column with the required information next to the normal overview.
  </para></listitem></varlistentry>
  <varlistentry><term><emphasis>Word wrap diff windows:</emphasis></term><listitem><para>
     Wrap lines when their length would exceed the width of a window.
  </para></listitem></varlistentry>
  <varlistentry><term><emphasis>Show Window A/B/C:</emphasis></term><listitem><para> Sometimes you want to use the space on
      the screen better for long lines. Hide the windows that are not important.
      (In the Windows-menu.)</para></listitem></varlistentry>
  <varlistentry><term><emphasis>Toggle Split Orientation:</emphasis></term><listitem><para>
      Switch between diff windows shown next to each other (A left of B left of C) or above
      each other (A above B above C). This should also help for long lines. (In the Windows-menu.)
      </para></listitem></varlistentry>
  <varlistentry><term><emphasis>Start a merge quickly:</emphasis></term><listitem><para>
      Sometimes you are viewing the deltas and decide to merge.
      <inlinemediaobject><imageobject><imagedata fileref="merge_current.png" format="PNG"/></imageobject></inlinemediaobject>
      "Merge current file" in the Directory-menu also works if you only compare
      two files. A single click starts the merge and uses the filename of the last
      input-file as the default output filename. (When this is used to restart
      a merge, then the output filename will be preserved.)</para></listitem></varlistentry>
</variablelist>
</sect2>

<sect2 id="shortcuts"><title>Configuring Keyboard-Shortcuts</title>
<para>
   Currently only the KDE-version supports user-configurable keyboard-shortcuts.
   (Menu Settings->Configure Shortcuts...)
</para>
</sect2>
</sect1>

<sect1 id="preprocessors"><title>Preprocessor Commands</title>
<para>
KDiff3 supports two preprocessor options.
</para><para>
<variablelist>
   <varlistentry><term><emphasis>Preprocessor-Command:</emphasis></term><listitem><para>
      When any file is read, it will be piped through this external command.
      The output of this command will be visible instead of the original file.
      You can write your own preprocessor that fulfills your specific needs.
      Use this to cut away disturbing parts of the file, or to automatically
      correct the indentation etc.
   </para></listitem></varlistentry>
   <varlistentry><term><emphasis>Line-Matching Preprocessor-Command:</emphasis></term><listitem><para>
      When any file is read, it will be piped through this external command. If
      a preprocessor-command (see above) is also specified, then the output of the
      preprocessor is the input of the line-matching preprocessor.
      The output will only be used during the line matching phase of the analysis.
      You can write your own preprocessor that fulfills your specific needs.
      Each input line must have a corresponding output line.
   </para></listitem></varlistentry>
</variablelist>
</para>
<para>
The idea is to allow the user greater flexibility while configuring the diff-result.
But this requires an external program, and many users don't want to write one themselves.
The good news is that very often <command>sed</command> or <command>perl</command> 
will do the job. 
</para>
<para>Example: Simple testcase: Consider file a.txt (6 lines):
<screen>
      aa
      ba
      ca
      da
      ea
      fa
</screen>
And file b.txt (3 lines):
<screen>
      cg
      dg
      eg
</screen>
Without a preprocessor the following lines would be placed next to each other:
<screen>
      aa - cg
      ba - dg
      ca - eg
      da
      ea
      fa
</screen>
This is probably not wanted since the first letter contains the actually interesting information.
To help the matching algorithm to ignore the second letter we can use a line matching preprocessor 
command, that replaces 'g' with 'a':
<screen>
   <command>sed</command> 's/g/a/'
</screen>
With this command the result of the comparison would be:
<screen>
      aa
      ba
      ca - cg
      da - dg
      ea - eg
      fa
</screen>
Internally the matching algorithm sees the files after running the line matching preprocessor,
but on the screen the file is unchanged. (The normal preprocessor would change the data also on 
the screen.)
</para>

<sect2 id="sedbasics"><title><command>sed</command> Basics</title>
<para>
This section only introduces some very basic features of <command>sed</command>. For more
information see <ulink url="info:/sed">info:/sed</ulink> or 
<ulink url="http://www.gnu.org/software/sed/manual/html_mono/sed.html">
http://www.gnu.org/software/sed/manual/html_mono/sed.html</ulink>.
A precompiled version for Windows can be found at <ulink url="http://unxutils.sourceforge.net">
http://unxutils.sourceforge.net</ulink>.
Note that the following examples assume that the <command>sed</command>-command is in some 
directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute
path for the command. Also note that the following examples use the single quotation mark (') which won't work for Windows. 
On Windows you should use the double quotation marks (") instead.
</para>
<para>
In this context only the <command>sed</command>-substitute-command is used:
<screen>
   <command>sed</command> 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>'
</screen>
Before you use a new command within KDiff3, you should first test it in a console.
Here the <command>echo</command>-command is useful. Example:
<screen>
   <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/'
   -> obrakadabra
</screen>
This example shows a very simple sed-command that replaces the first occurance 
of "a" with "o". If you want to replace all occurances then you need the "g"-flag:
<screen>
   <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g'
   -> obrokodobro
</screen>
The "|"-symbol is the pipe-command that transfers the output of the previous 
command to the input of the following command. If you want to test with a longer file
then you can use <command>cat</command> on Unix-like systems or <command>type</command> 
on Windows-like systems. <command>sed</command> will do the substitution for each line.
<screen>
   <command>cat</command> <replaceable>filename</replaceable> | <command>sed</command> <replaceable>options</replaceable>
</screen>
</para>
</sect2>
<sect2 id="sedforkdiff3"><title>Examples For <command>sed</command>-Use In KDiff3</title>
<sect3><title>Ignoring Other Types Of Comments</title>
<para>
Currently KDiff3 understands only C/C++ comments. Using the
Line-Matching-Preprocessor-Command you can also ignore
other types of comments, by converting them into C/C++-comments.

Example: To ignore comments starting with "#", you would like to convert them
to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get 
an effect. An appropriate Line-Matching-Preprocessor-Command would be:

<screen>
   <command>sed</command> 's/#/\/\//'
</screen>
Since for <command>sed</command> the "/"-character has a special meaning, it is necessary to place the 
"\"-character before each "/" in the replacement-string. Sometimes the "\" is required
to add or remove a special meaning of certain characters. The single quotation marks (') before 
and after the substitution-command are important now, because otherwise the shell will
try to interpret some special characters like '#', '$' or '\' before passing them to 
<command>sed</command>. Note that on Windows you will need the double quotation marks (") here. Windows
substitutes other characters like '%', so you might have to experiment a little bit.
</para>
</sect3>
<sect3><title>Caseinsensitive Diff</title>
<para>
Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase:
<screen>
   <command>sed</command> 's/\(.*\)/\U\1/'
</screen>
Here the ".*" is a regular expression that matches any string and in this context matches 
all characters in the line. 
The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)".
The "\U" converts the inserted text to uppercase.
</para>
</sect3>

<sect3><title>Ignoring Version Control Keywords</title>
<para>
CVS and other version control systems use several keywords to insert automatically
generated strings (<ulink url="info:/cvs/Keyword substitution">info:/cvs/Keyword substitution</ulink>).
All of them follow the pattern "$KEYWORD generated text$". We now need a
Line-Matching-Preprocessor-Command that removes only the generated text:
<screen>
   <command>sed</command> 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/'
</screen>
The "\|" separates the possible keywords. You might want to modify this list 
according to your needs.
The "\" before the "$" is necessary because otherwise the "$" matches the end of the line.
</para>
<para>
While experimenting with <command>sed</command> you might come to understand and even like
these regular expressions. They are useful because there are many other programs that also 
support similar things.
</para>
</sect3>

<sect3><title>Ignoring Numbers</title>
<para>
Ignoring numbers actually is a built-in option. But as another example, this is how
it would look as a Line-Matching-Preprocessor-command.
<screen>
   <command>sed</command> 's/[0123456789.-]//g'
</screen>
Any character within '[' and ']' is a match and will be replaced with nothing.
</para>
</sect3>

<sect3><title>Ignoring Certain Columns</title>
<para>
Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are
other columns you want to preserve for analysis. In the following example the first five columns (characters) are 
ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved.
<screen>
   <command>sed</command> 's/.....\(..........\).....\(.*\)/\1\2/'
</screen>
Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first 
and second pair of "\(" and "\)" denoting the text to be preserved.
</para>
</sect3>

<sect3><title>Combining Several Substitutions</title>
<para>
Sometimes you want to apply several substitutions at once. You can then use the 
semicolon ';' to separate these from each other. Example:
<screen>
   <command>echo</command> abrakadabra | <command>sed</command> 's/a/o/g;s/\(.*\)/\U\1/'
   -> OBROKODOBRO
</screen>
</para>
</sect3>

<sect3><title>Using <command>perl</command> instead of <command>sed</command></title>
<para>
Instead of <command>sed</command> you might want to use something else like 
<command>perl</command>.
<screen>
   <command>perl</command> -p -e 's/<replaceable>REGEXP</replaceable>/<replaceable>REPLACEMENT</replaceable>/<replaceable>FLAGS</replaceable>'
</screen>
But some details are different in <command>perl</command>. Note that where 
<command>sed</command> needed "\(" and "\)" <command>perl</command>
requires the simpler "(" and ")" without preceding '\'. Example:
<screen>
   <command>sed</command> 's/\(.*\)/\U\1/'
   <command>perl</command> -p -e 's/(.*)/\U\1/'
</screen>
</para>
</sect3>
</sect2>

<sect2><title>Order Of Preprocessor Execution</title>
<para>
The data is piped through all internal and external preprocessors in the 
following order:
</para>
<itemizedlist>
<listitem><para>Normal preprocessor,</para></listitem>
<listitem><para>Line-Matching-Preprocessor,</para></listitem>
<listitem><para>Ignore case (conversion to uppercase),</para></listitem>
<listitem><para>Detection of C/C++ comments,</para></listitem>
<listitem><para>Ignore numbers,</para></listitem>
<listitem><para>Ignore white space</para></listitem>
</itemizedlist>
<para>
The data after the normal preprocessor will be preserved for display and merging. The
other operations only modify the data that the line-matching-diff-algorithm sees.
</para><para>
In the rare cases where you use a normal preprocessor note that 
the line-matching-preprocessor sees the output of the normal preprocessor as input.
</para>
</sect2>

<sect2><title>Warning</title>
<para>
The preprocessor-commands are often very useful, but as with any option that modifies
your texts or hides away certain differences automatically, you might accidently overlook 
certain differences and in the worst case destroy important data.
</para><para>
For this reason during a merge if a normal preprocessor-command is being used KDiff3 
will tell you so and ask you if it should be disabled or not. 
But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until
all conflicts are solved. If you disabled "Show White Space" then the differences that
were removed with the Line-Matching-Preprocessor-command will also be invisible. If the 
Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable 
"Show White Space". If you don't wan't to merge these less important differences manually
you can select "Choose [A|B|C] For All Unsolved Whitespace Conflicts" in the Merge-menu.
</para>
</sect2>
</sect1>
</chapter>


<chapter id="dirmerge"><title>Directory Comparison and Merge with KDiff3</title>
<sect1 id="dirmergeintro"><title>Introduction</title>
<para>
   Often programmers must modify many files in a directory to achieve their
   purpose. For this KDiff3 also lets you compare and merge complete directories
   recursively!
</para><para>
   Even though comparing and merging directories seems to be quite obvious,
   there are several details that you should know about. Most important is of
   course the fact that now many files might be affected by each operation.
   If you don't have backups of your original data, then it can be very hard
   or even impossible to return to the original state. So before starting a merge,
   make sure that your data is safe, and going back is possible. If you make
   an archive or use some version control system is your decision, but even
   experienced programmers and integrators need the old sources now and then.
   And note that even though I (the author of KDiff3) try to do my best, I can't
   guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY
   whatsoever for this program. So be humble and always keep in mind:
</para>
<blockquote><para>
   <emphasis>To err is human, but to really mess things up you need a computer.</emphasis>
</para></blockquote>
<para>
So this is what this program can do for you: KDiff3 ...
</para>
<itemizedlist>
     <listitem><para>... reads and compares two or three directories recursively,</para></listitem>
     <listitem><para>... takes special care of symbolic links,</para></listitem>
     <listitem><para>... lets you browse files on mouse double click,</para></listitem>
     <listitem><para>... for each item proposes a merge operation, which you can change
                         before starting the directory merge,</para></listitem>
     <listitem><para>... lets you simulate the merge and lists the actions that would
                         take  place, without actually doing them,</para></listitem>
     <listitem><para>... lets you really do the merge, and lets you interact whenever
                         manual interaction is needed,</para></listitem>
     <listitem><para>... lets you run the selected operation for all items (key F7) or the selected item (key F6),</para></listitem>
     <listitem><para>... lets you continue the merge after manual interaction with key F7,</para></listitem>
     <listitem><para>... optionally creates backups, with the ".orig" extension,</para></listitem>
     <listitem><para>...</para></listitem>
</itemizedlist>
</sect1>

<sect1 id="startingdirmerge"><title>Starting Directory Comparison Or Merge</title>
<para>
   This is very similar to the single file merge and comparison. You just
   have  to specify directories on the command line or in the file-open
   dialog.
</para>
<sect2><title>Compare/Merge two directories: </title>
<screen>
   <command>kdiff3</command> <replaceable>dir1 dir2</replaceable>
   <command>kdiff3</command> <replaceable>dir1 dir2</replaceable> -o <replaceable>destdir</replaceable>
</screen>
<para>
   If no destination directory is specified, then KDiff3 will use <replaceable>dir2</replaceable>.
</para>
</sect2>

<sect2><title>Compare/Merge three directories: </title>
<screen>
   <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable>
   <command>kdiff3</command> <replaceable>dir1 dir2 dir3</replaceable> -o <replaceable>destdir</replaceable>
</screen>
<para>
   When three directories are merged then <replaceable>dir1</replaceable>
   is used as the base for the merge.
   If no destination directory is specified, then KDiff3 will use <replaceable>dir3</replaceable>
   as the  destination directory for the merge.
</para>

<para>
   Note that only the comparison starts automatically, not the merge. For this you first must
   select a menu entry or the key F7. (More details later.)
</para>
</sect2>
</sect1>

<sect1 id="dirmergevisible"><title>Visible Information</title>
<para>
   While reading the directories a message-box appears that informs you of
   the progress. If you abort the directory scan, then only files that have
   been  compared until then will be listed.
</para><para>
   When the directory scan is complete then KDiff3 will show a listbox with
   the results left, ...
</para>
<screenshot><mediaobject>
<imageobject><imagedata fileref="dirbrowser.png" format="PNG"/></imageobject> <!--alt="Image of the directory browser."-->
</mediaobject></screenshot>
<para>
   ... and details about the currently selected item on the right:
</para>
<screenshot><mediaobject>
<imageobject><imagedata fileref="iteminfo.png" format="PNG"/></imageobject>
   <!--alt="Image with information about the selected item."-->
</mediaobject></screenshot>

<sect2 id="name"><title>The Name Column</title>
<para>
   Each file and directory that was found during the scan is shown here in
   a tree. You can select an item by clicking it with the mouse once.
</para><para>
   The directories are collapsed by default. You can expand and collapse
   them by clicking on the "+"/"-" or by double-clicking the item or
   by using  the left/right-arrow-keys. The "Directory"-menu also contains two
   actions "Fold all subdirs" and "Unfold all subdirs" with which you can
   collapse or expand all directories at once.
</para><para>
   If you double-click a file item then the file comparison starts and the
   file-diff-window will appear.
</para>
<para>
   The image in the name column reflects the file type in the first
   directory  ("A"). It can be one of these:
</para>
<itemizedlist>
     <listitem><para>Normal file</para></listitem>
     <listitem><para>Normal directory (directory-image)</para></listitem>
     <listitem><para>Link to a file (file-image with a link arrow)</para></listitem>
     <listitem><para>Link to a directory (directory-image with a link arrow)</para></listitem>
</itemizedlist>
<para>
   If the file type is different in the other directories, then this is visible
   in the columns A/B/C and in the window that shows the details about the selected
   item. Note that for such a case no merge operation can be selected automatically.
   When starting the merge, then the user will be informed of problems of that
   kind.
</para>
</sect2>

<sect2 id="coloring"><title>The Columns A/B/C and the Coloring Scheme</title>
<para>
   As can be seen in the image above the colors red, green, yellow and black
   are used in the columns A/B/C.
</para>
<itemizedlist>
     <listitem><para>Black: This item doesn't exist in this directory.</para></listitem>
     <listitem><para>Green: Newest item.</para></listitem>
     <listitem><para>Yellow: Older than green, newer than red.</para></listitem>
     <listitem><para>Red: Oldest item.</para></listitem>
</itemizedlist>
<para>
   But for items that were identical in the comparison their color also is
   identical even if the age is not.
</para><para>
   Directories are considered equal if all items they contain are identical.
   Then they also will have the same color. But the age of a directory is not
   considered for its color.
</para><para>
   The idea for this coloring scheme I came upon in
   <ulink url="http://samba.org/cgi-bin/cvsweb/dirdiff">dirdiff</ulink>. The colors
   resemble the colors of a leaf that is green when new, turns yellow later and red
   when old.
</para>

</sect2><sect2 id="operation"><title>The Operation Column</title>
<para>
   After comparing the directories KDiff3 also evaluates a proposal for a
   merge  operation. This is shown in the "Operation" column. You can modify
   the operation  by clicking on the operation you want to change. A small menu
   will popup and allows you to select an operation for that item. (You can also
   select the most needed operations via keyboard.
   Ctrl+1/2/3/4/Del will select A/B/C/Merge/Delete respectively if available.)
   This operation will be executed during the merge. It depends on the item and
   on the merge-mode you are in, what operations are available. The merge-mode is one of
</para>
<itemizedlist>
     <listitem><para>Three directory-merge ("A" is treated as older base of both).</para></listitem>
     <listitem><para>Two directory-merge.</para></listitem>
     <listitem><para>Two directory-sync-mode (activate via option "Synchronize Directories").</para></listitem>
</itemizedlist>
<para>
   In three directory merge the operation proposal will be: If for an item ...
</para>
<itemizedlist>
     <listitem><para>... all three directories are equal: Copy from C</para></listitem>
     <listitem><para>... A and C are equal but B is not: Copy from B (or if B does not
                         exist, delete the destination if exists)</para></listitem>
     <listitem><para>... A and B are equal but C is not: Copy from C (or if C does not
                         exist, delete the destination if exists)</para></listitem>
     <listitem><para>... B and C are equal but A is not: Copy from C (or if C does not
                         exist, delete the destination if exists)</para></listitem>
     <listitem><para>... only A exists: Delete the destination (if exists)</para></listitem>
     <listitem><para>... only B exists: Copy from B</para></listitem>
     <listitem><para>... only C exists: Copy from C</para></listitem>
     <listitem><para>... A, B and C are not equal: Merge</para></listitem>
     <listitem><para>... A, B and C don't have the same file type (e.g. A is a directory,
                         B is a file): "Error: Conflicting File Types". While such items exist the
                         directory merge cannot start.</para></listitem>
</itemizedlist>
<para>
   In two directory merge the operation proposal will be: If for an item ...
</para>
<itemizedlist>
     <listitem><para>... both directories are equal: Copy from B</para></listitem>
     <listitem><para>... A exists, but not B: Copy from A</para></listitem>
     <listitem><para>... B exists, but not A: Copy from B</para></listitem>
     <listitem><para>... A and B exist but are not equal: Merge</para></listitem>
     <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
                         B is a file): "Error: Conflicting File Types". While such items exist the
                         directory merge cannot start.</para></listitem>
</itemizedlist>
<para>
   Sync-mode is active if only two directories and no explicit destination
   were specified and if the option "Synchronize directories" is active. KDiff3
   then selects a default operation so that both directories are the same afterwards.
   If for an item ...
</para>
<itemizedlist>
     <listitem><para>... both directories are equal: Nothing will be done.</para></listitem>
     <listitem><para>... A exists, but not B: Copy A to B</para></listitem>
     <listitem><para>... B exists, but not A: Copy B to A</para></listitem>
     <listitem><para>... A and B exist, but are not equal: Merge and store the result
                         in  both directories. (For the user the visible save-filename is B,
                         but then KDiff3 copies B also to A.)</para></listitem>
     <listitem><para>... A and B don't have the same file type (e.g. A is a directory,
                         B is a file): "Error: Conflicting File Types". While such items exist the
                         directory merge cannot start.</para></listitem>
</itemizedlist>
<para>
   When two directories are merged and the option "Copy newer instead of merging" is selected,
   then KDiff3 looks at the dates and proposes to choose the newer file. If the files are not
   equal but have equal dates, then the operation will contain
   "Error: Dates are equal but files are not." While such items exist the
   directory merge cannot start.
</para>
</sect2>

<sect2 id="status"><title>The Status Column</title>
<para>
   During the merge one file after the other will be processed. The status
   column will show "Done" for items where the merge operation has succeeded,
   and other texts if something unexpected happened. When a merge is complete,
   then you should make a last check to see if the status for all items is
   agreeable.
</para>
</sect2>

<sect2 id="statisticscolulmns"><title>Statistics Columns</title>
<para>
   When the file comparison mode "Full Analysis" is enabled in the options, then
   KDiff3 will show extra columns containing the numbers of unsolved, solved, nonwhite and whitespace
   conflicts. (The solved-column will only show when comparing or merging three directories.)
</para>
</sect2>

</sect1>


<sect1 id="dothemerge"><title>Doing A Merge</title>
<para>
   You can either merge the currently selected item (file or directory), or all items.
   When you have made all your operation choices (in all subdirectories too)
   then you can start the merge.
</para><para>
   Be aware that if you didn't specify a destination directory explicitely,
   then the destination will be "C" in three directory mode, "B" in two directory
   merge mode, and in sync-mode it will be "A" or/and "B".
</para><para>
   If you have specified a destination directory also check that all items
   that should be in the output, are in the tree. There are some options that
   cause certain items to be omitted from the directory comparison and merge.
   Check these options to avoid unpleasant surprises:
</para>
<itemizedlist>
     <listitem><para>"Recursive Directories": If this is off, then items in subdirectories
                     will not be found.</para></listitem>
     <listitem><para>"Pattern"/"Anti-Pattern": Include/exclude items that match</para></listitem>
     <listitem><para>"Exclude Hidden Files"</para></listitem>
     <listitem><para>"List only Deltas": Files that match in all directories don't appear
                     in the tree, and hence also not in the destination.</para></listitem>
</itemizedlist>
<para>
   (In the current version, you must do a rescan via menu "Directory"->"Rescan"
   yourself, after changing options affecting the directory scan.)
</para><para>
   If you are satisfied so far, the rest is easy.
</para><para>
   To merge all items: Select "Start/Continue directory merge" in the "Directory"-menu
   or press F7 (which is the shortcut).
   To merge only the current item: Select "Run Operation For Current Item"
   or press F6.
</para><para>
   If  due to conflicting filetypes still some items with invalid operations
   exist, then a messagebox will appear and these items will be pointed out,
   so you can select a valid operation for the item.
</para><para>
   If you merge all items a dialog will appear giving you the options "Do it", "Simulate
   it" and "Cancel".
</para>
<itemizedlist>
     <listitem><para>Select "Simulate it" if you want to see what would be done without
                     actually doing it. A verbose list of all operations will be shown.</para></listitem>
     <listitem><para>Otherwise select "Do it" to really start merging.</para></listitem>
</itemizedlist>
<para>
   Then KDiff3 will run the specified operation for all items. If manual
   interaction  is required (single file merge), then a merge window will open
   (<link linkend="dirmergebigscreenshot">see the big screenshot</link>).
</para><para>
   When you have finished with a file, again select "Start/Continue directory
   merge" or the key F7. If you haven't saved yet, a dialog will ask you to
   do so. Then KDiff3 will continue with the next item.
</para><para>
   When KDiff3 encounters an error, it will tell you so and will show the
   verbose-status-information. At the bottom of this list, there will be some
   error messages which should help you to understand the cause of the problem.
   When you continue merging (F7 key) KDiff3 will give you the choice to retry
   or skip the item that caused the problem. This means that before continuing
   you can choose another operation or solve the problem by other means.
</para><para>
   When the merge is complete, then KDiff3 will inform you via a message
   box.
</para><para>
   If some items were merged individually then KDiff3 remembers this (while this
   merge-session goes on), and doesn't merge them again when later the merge for
   all items is run. Even when the merge was skipped or nothing was saved these
   items count as completed. Only when you change the merge operation the item
   will be merged again.
</para>
</sect1>

<sect1 id="dirmergeoptions"><title>Options for Comparing and Merging Directories</title>
<para>
   The KDiff3-preferences (menu "Settings"-&gt;"Configure KDiff3") now has
   a section called "Directory Merge" with these options:
</para>

<variablelist>
   <varlistentry><term><emphasis>Recursive Directories:</emphasis></term><listitem><para> Select whether to search directories
         recursively.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>File Pattern(s):</emphasis></term><listitem><para> Only files that match any pattern here will
         be put in the tree. More than one pattern may be specified here via using
         the semicolon ";" as separator. Valid wildcards: '*' and '?'. (e.g. "*.cpp;*.h").
         Default is "*". Directories need not match this pattern.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Anti-Pattern(s):</emphasis></term><listitem><para> Files and directories that match this pattern
         will be excluded from the tree. More than one pattern may be specified here
         via using the semicolon ";" as separator. Valid wildcards: '*' and '?'. Default
         is "*.orig;*.o".</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Use CVS-Ignore:</emphasis></term><listitem><para>
         Ignore files and directories that would also be ignored by CVS.
         Many automatically generated files are ignored by CVS.
         The big advantage is that this can be directory specific via a local ".cvsignore"-file.
         (See <ulink url="info:/cvs/cvsignore">info:/cvs/cvsignore</ulink>.)</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Find Hidden Files and Directories:</emphasis></term><listitem><para> On some filesystems files
         have an "Hidden"-attribute. On other systems a filename starting with a dot
         "." causes it to be hidden. This option allows you to decide whether to
         include  these files in the tree or not. Default is on.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Follow File Links:</emphasis></term><listitem><para> For links to files: When disabled, then
         the symbolic links are compared. When enabled, then the files behind the
         links are compared. Default is off.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Follow Directory Links:</emphasis></term><listitem><para> For links to directories: When disabled,
         then the symbolic links will be compared. When enabled then the link will
         be treated like a directory and it will be scanned recursively. (Note that
         the program doesn't check if the link is "recursive". So for example a directory
         that contains a link to the directory would cause an infinite loop, and after
         some time when the stack overflows or all memory is used up, crash the program.)
         Default is off.</para></listitem></varlistentry>   
   <varlistentry><term><emphasis>List only deltas:</emphasis></term><listitem><para> Only items that are not equal in all input
         directories will be listed and only the changed files are visible. Hence
         files that are equal in all directories won't be copied during a merge and
         if the destination dir does not contain the files before the merge, you might
         miss some files later. (This option is likely to be changed in a later version.)
         Default is off.</para></listitem></varlistentry>

   <varlistentry><term><emphasis>File Comparison Mode:</emphasis></term><listitem><para>
<variablelist>            
   <varlistentry><term><emphasis>Binary Comparison:</emphasis></term><listitem><para>
         This is the default file comparison mode.
         </para></listitem></varlistentry>         
   <varlistentry><term><emphasis>Full Analysis:</emphasis></term><listitem><para>
         Do a full analysis of each file and show the statistics information columns.
         (Number of solved, unsolved, nonwhite and white conflicts.)
         The full analysis is slower than a simple binary analysis, and much
         slower when used on files that don't contain text. 
         (Specify the appropriate file-antipatterns.)
         </para></listitem></varlistentry>         
   <varlistentry><term><emphasis>Trust the modification date:</emphasis></term><listitem><para> If you compare big directories
         over a slow network, it might be faster to compare the modification dates
         and file length alone. But this speed improvement comes with the price of
         a little uncertainty. Use this option with care. Default is off.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Trust the size:</emphasis></term><listitem><para>
         Similar to trusting the modification date. No real comparison happens. Two
         files are considered equal if their file-sizes are equal. This is useful
         when the file-copy operation didn't preserve the modification date.
         Use this option with care. Default is off.</para></listitem></varlistentry>
</variablelist></para></listitem></varlistentry>
         
   <varlistentry><term><emphasis>Synchronize Directories:</emphasis></term><listitem><para> Activates "Sync-Mode" when two directories
         are compared and no explicit destination directory was specified. In this
         mode the proposed operations will be chosen so that both source directories
         are equal afterwards. Also the merge result will be written to both directories.
         Default is off.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Copy newer instead of merging:</emphasis></term><listitem><para> Instead of merging the proposed
         operation will copy the newer source if changes happened. (Considered unsafe,
         because it implies that the knowledge, that the other file hasn't been edited
         too. Check to make sure in every case.) Default is off.</para></listitem></varlistentry>
   <varlistentry><term><emphasis>Backup files:</emphasis></term><listitem><para> If a file or complete directory is replaced
         by  another or is deleted then the original version will be renamed with an
         ".orig"  extension. If an old backup file with ".orig" extension already exists
         then  this will be deleted without backup. This also affects the normal merging
         of single files, not only in directory-merge mode. Default is on.</para></listitem></varlistentry>
</variablelist>
</sect1>

<sect1 id="other"><title>Other Functions</title>
<sect2><title>Split/Full Screen Mode</title>
<para>
   Usually the directory merge list view remains visible while a single file
   is compared or merged. With the mouse you can move the the splitter bar that
   separates the file list from the text-diff windows. If you don't want this,
   you can disable "Split Screen View" in the "Directory"-menu. Then you can
   use "Toggle View" in the "Directory"-menu to switch between the file list
   and the text-diff view that then occupy the full screen.
</para>
</sect2>
<sect2><title>Comparing or Merging a Single File</title>
<para>
   Probably you will prefer a simple double mouse click on a file in order
   to compare it. Nevertheless there also exists an entry in the "Directory"-menu.
   You can also directly merge a single file, without starting the directory
   merge via the "Merge single file" in the "Directory"-Menu. On saving the
   result, the status will be set to done, and the file will not be merged again
   if a directory merge is started.
</para><para>
   But note that this status information will be lost when you rerun a directory
   scan: "Directory"-menu: "Rescan"
</para>
</sect2>
</sect1>
</chapter>

<chapter id="misc">
<title>Miscellaneous Topics</title>
<sect1 id="networktransparency">
<title>Networktransparency via KIO</title>
<sect2><title>KIO-Slaves</title>
<para>
KDE supports networktransparency via KIO-slaves. KDiff3 uses this
for reading input files and for scanning directories.
This means that you can specify files and directories on local and
remote ressources via URLs.
</para><para>
Example:
</para><para>
<screen>
   <command>kdiff3</command> test.cpp  ftp://ftp.faraway.org/test.cpp
   <command>kdiff3</command> tar:/home/hacker/archive.tar.gz/dir ./dir
</screen>
</para>
<para>The first line compares a local file with a file on an FTP-server. The second line
compares a directory within an compressed archive with a local directory.
</para><para>
Other KIO-slaves that are interesting are:
</para>
<itemizedlist>
<listitem><para>Files from the WWW (http:),</para></listitem>
<listitem><para>Files from the FTP (ftp:),</para></listitem>
<listitem><para>Encrypted file transfer (fish:, sftp:),</para></listitem>
<listitem><para>Windows-ressources (smb:),</para></listitem>
<listitem><para>Local files (file:),</para></listitem>
</itemizedlist>
<para>
Other things that are possible, but probably less useful are:
</para>
<itemizedlist>
<listitem><para>Man-pages (man:),</para></listitem>
<listitem><para>Info-pages (info:),</para></listitem>
</itemizedlist>
</sect2>

<sect2><title>How To Write URLs</title>
<para>
   An URL has a different syntax compared with paths for local files and directories.
   Some things should be considered:
</para>
<itemizedlist>
<listitem><para>
   A path can be relative and can contain "." or "..". This is not possible for URLs
   which are always absolute.
</para></listitem><listitem><para>
   Special characters must be written with "escaping". ("#"->"%23", space->"%20", etc.)
   E.g. A file with the name "/#foo#" would have the URL "file:/%23foo%23".
</para></listitem><listitem><para>
   When URLs don't work as expected, try to open them in Konqueror first.
</para></listitem>
</itemizedlist>

</sect2>

<sect2><title>Capabilities of KIO-Slaves</title>
<para>
   Networktransparency has one drawback: Not all ressources have the same cababilities.
</para><para>
   Sometimes this is due to the filesystem of the server, sometimes due to the protocol.
   Here is a short list of restrictions:
</para>
<itemizedlist>
<listitem><para>
   Sometimes there is no support for links.
</para></listitem><listitem><para>
   Or there is no way to distinguish if a link points to a file or a directory; always
   assuming a file. (ftp:, sftp:).
</para></listitem><listitem><para>
   Can't always determine the filesize.
</para></listitem><listitem><para>
   Limited support for permissions.
</para></listitem><listitem><para>
   No possibility to modify permissions or modification time, so permissions or time
   of a copy will differ from the original. (See the option "Trust the size".)
   (Modifying permissions or modification time is only possible for local files.)
</para></listitem>
</itemizedlist>
</sect2>
</sect1>

<sect1 id="kpart">
<title>Using &kdiff3; as a KPart</title>
<para>
&kdiff3; is a KPart. Currently it implements the KParts::ReadOnlyPart-interface.
</para><para>
It's main use is as difference-viewer in KDevelop. KDevelop always starts the
internal difference viewer first. To invoke KDiff3 press the right mouse button
on the difference viewer window and select "Show in KDiff3Part" from the contextmenu.
</para><para>
KDiff3 normally requires two complete files as input. When used as part KDiff3
will assume that the inputfile is a patch-file in the unified format. KDiff3
then retrieves the original filenames from the patch-file. At least one of
the two files must be available. KDiff3 will then invoke <command>patch</command> to
recreate the second file.
</para><para>
In Konqueror you can select a patch-file and select "Preview in"-"KDiff3Part" from
the contextmenu. Be aware that this won't work if none of the original files are
available, and it is not reliable if the original file(s) have changed since the
patch-file was generated.
</para><para>
When run as a part KDiff3 only provides the a two-file-diff, a very small toolbar
and menu. Merging or directory-comparison are not supported then.
</para>
</sect1>
</chapter>

<chapter id="faq">
<title>Questions and Answers</title>

&reporting.bugs;
&updating.documentation;

<qandaset id="faqlist">

<qandaentry><question><para>
   Why is it called "KDiff3"?
</para></question><answer><para>
   Tools named "KDiff" and "KDiff2" (now called "Kompare") already exist. Also "KDiff3" should suggest
   that it can merge like the "diff3"-tool in the Diff-Tool collection.
</para></answer></qandaentry>

<qandaentry><question><para>
   Why did I release it under GPL?
</para></question><answer><para>
   I'm using GPL programs for a very long time now and learned very much
   by  having a look at many of the sources. Hence this is my "Thank You"
   to   all  programmers that also did so or will do the same.
</para></answer></qandaentry>

<qandaentry><question><para>
   Some buttons and functions are missing. What's wrong?
</para></question><answer><para>
   You compiled from source but you probably didn't specify the correct KDE-prefix
   with configure. By default configure wants to install in /usr/local but then KDE can't
   find the user-interface ressource file (i.e. kdiff3ui.rc). The README-file contains
   more information about the correct prefix.
</para></answer></qandaentry>

<qandaentry><question><para>
   Often lines that are similar but not identical appear next to each other
   but sometimes not. Why?
</para></question><answer><para>
   Lines where only the amount of white space characters is different
   are   treated as "equal" at first, while just one different non-white character
   causes the lines to be "different". If similar lines appear next to each
   other, this actually is coincidence but this fortunately is often the case.
</para></answer></qandaentry>

<qandaentry><question><para>
   Why must all conflicts be solved before the merge result can be saved?
</para></question><answer><para>
   For each equal or different section the editor in the merge result
   window    remembers where it begins or ends. This is needed so that conflicts
   can  be solved manually by simply selecting the source button (A, B or C).
   This  information is lost while saving as text and it is too much effort to
   create  a special file format that supports saving and restoring all necessary
   information.
</para></answer></qandaentry>

<qandaentry><question><para>
   Why does the editor in the merge result window not have an "undo"-function?
</para></question><answer><para>
  This was too much effort until now. You can always
  restore a version from one source (A, B or C) by clicking the respective
  button. For big editing the use of another editor is recommended anyway.
</para></answer></qandaentry>

<qandaentry><question><para>
   When I removed some text, then suddenly "&lt;No src line&gt;" appeared
   and can't be deleted. What does that mean and how can one remove this?
</para></question><answer><para>
   For each equal or different section the editor in the merge result
   window    remembers where it begins or ends. "&lt;No src line&gt;" means
   that    there is nothing left in a section, not even a new line character.
   This  can happen either while merging automatically or by editing. This is
   no problem,   since this hint won't appear in the saved file. If you want
   the orignal source  back just select the section (click on the left summary
   column) and then click the source button with the needed contents (A/B or
   C).
</para></answer></qandaentry>

<qandaentry><question><para>
   Why doesn't KDiff3 support syntax-highlighting?
</para></question><answer><para>
   KDiff3 already uses many colors for difference highlighting. More
   highlighting    would be confusing. Use another editor for this.
</para></answer></qandaentry>

<qandaentry><question><para>
   There is so much information here, but your question is still not answered?
</para></question><answer><para>
   Please send me your question. I appreciate every comment.
</para></answer></qandaentry>

</qandaset>
</chapter>

<chapter id="credits">

<title>Credits and License</title>

<para>
&kdiff3; - File and Directory Comparison and Merge Tool
</para>
<para>
Program copyright 2002-2004 Joachim Eibl <email>joachim.eibl at gmx.de</email>
</para>
<para>
Several cool ideas and bugreports came from colleagues and many people out in the Wild Wild Web. Thank you!
</para>

<para>
Documentation Copyright &copy; 2002-2004 Joachim Eibl <email>joachim.eibl at gmx.de</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->


&underGPL;        	 <!-- GPL License -->

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="getting-kdiff3">
<title>How to obtain &kdiff3;</title>

<para>
You can download the latest version of KDiff3 from its homepage <ulink url="http://kdiff3.sourceforge.net">http://kdiff3.sourceforge.net</ulink>.
</para><para>
KDiff3 is also available for other platforms. See the homepage for details.
</para>


</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>
   In order to successfully use all features of &kdiff3;, you need &kde; >3.1.
</para><para>
   For information about how to run KDiff3 on other platforms without KDE please see the
   <ulink url="http://kdiff3.sourceforge.net">homepage</ulink>.
</para><para>
You can find a list of changes at <ulink
url="http://kdiff3.sourceforge.net/ChangeLog">http://kdiff3.sourceforge.net/ChangeLog</ulink>
or in the "ChangeLog"-file of the source package.
</para>
</sect1>

<sect1 id="compilation">
<title>Compilation and Installation</title>

<para>In order to compile and install &kdiff3; on a system with KDE, type the
following in the base directory of the &kdiff3; distribution:</para>

<screen><prompt>%</prompt> <userinput><command>./configure --prefix=<replaceable>kde-dir</replaceable></command></userinput>
<prompt>%</prompt> <userinput><command>make</command></userinput>
<prompt>%</prompt> <userinput><command>make</command> install</userinput>
</screen>
<para>
<replaceable>kde-dir</replaceable> specifies the directory
containing KDE on your system. If you are not sure, read the README-file for details.
</para>
<para>Since &kdiff3; uses <command>autoconf</command> and
<command>automake</command> you should have no trouble compiling it. Should you
run into problems please report them to the &kde; mailing lists.</para>

</sect1>

</appendix>

&documentation.index;
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:

vim:tabstop=2:shiftwidth=2:expandtab
-->