KDiff3 - Text Diff And Merge Tool
Author: Joachim Eibl
Copyright 2002-2003
Documentation for version 0.9.60.
KDiff3 is a program that
- compares two or three text input files,
- shows the differences line by line and character by character(!),
- provides an automatic merge-facility and
- an editor for comfortable solving of merge-conflicts,
- has an intuitive graphical user interface,
- and you can also compare and merge directories!
KDiff3 Home
Screenshots
Features
Documentation of single file comparison and merge
Documentation of the directory comparison
and merge
Questions and Answers
Screenshots
This screenshot shows the difference between two text files (using
an early version of KDiff3):
This screenshot shows three input files being merged:
A big screenshot with directory comparison
Features
Line-By-Line And Char-By-Char Diff-Viewer
By using the possiblities of a graphical color display KDiff3 shows
exactly what the difference is:
See White-Space Differences At One Glance
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.
Triple-Diff
Analyze three files and see where they differ.
The left/middle/right windows are named A/B/C and have the blue/green/magenta
color respectively.
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.
Comfortable Merge Of Two Or Three Input Files
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.
And ...
- Fast navigation via buttons.
- A mouse-click into a summary column sync's all windows to show the same position.
- Select and copy from any window and paste into the merge result window.
- Overview column that shows where the changes and conflicts are.
- The colors are adjustable to your specific preferences.
- Adjustable Tab size.
- Option to insert spaces instead of tabs.
- Open files comfortably via dialog or specify files on the command line.
- Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)
- Show the line numbers for each line.
Paste clipboard or drag text into a diff input window.
- ...
Diff Algorithm
Some graphical diff-tools are just front-ends to the good old command-line
Diff. This is reuse at its best but also limits the possiblities of any
front-end because a diff-analysis of each line is not provided by Diff.
I invented my own diff-algorithm, with the advantage that I could also
reuse it for a line comparison. This algorithm was optimized for use with
C/C++-source files.
But sometimes the results of my algorithm are not good enough. So you
can use an external diff-tool if you have one. Select "Use external diff"
in the "Diff-Options". The external diff will only be used for line matching.
The internal algorithm will still be used for finding the character differences
on each line.
Documentation of File Comparison And Merge
Command-Line Options
- Comparing 2 files:
kdiff3 file1 file2
- Merging 2 files:
kdiff3 file1 file2 -m
kdiff3 file1 file2 -o outputfile
- Comparing 3 files:
kdiff3 file1 file2 file3
- Merging 3 files:
kdiff3 file1 file2 file3 -m
kdiff3 file1 file2 file3 -o outputfile
Note that file1 will be treated as base of
file2 and file3.
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:
- Comparing 3 files:
kdiff3 dir1/filename dir2 dir3
For more information use:
kdiff3 --help
Open-Dialog
Since many input files must be selectable, the program has a special
open dialog:
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.
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.
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.
The "Configure..."-button opens the options-dialog, so that you can set
the options before running the analysis.
Paste and Drop Input
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".
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.
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.
Note 1: Currently you can't drag anything from KDiff3. Only dropping in the diff input
is supported.
Note 2: 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.
Interpreting The Information In The Input
Windows
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.)
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.)
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).
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.)
The vertical line separating the summary column and the text is interrupted
if the input file had no lines there.
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.
Merging And The Merge Output Editor Window
This window 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.
!!! Saving is disabled until all conflicts are resolved !!! (Use the "Go
to prev/next unsolved conflicts"-buttons to find the remaining conflicts.)
With only two input files every difference is also a conflict that must
be solved manually.
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.
The merge output editor window also has a summary column. 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 "<Merge Conflict>", 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.
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.
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.
Besides, you can directly edit any line. The summary column will show "m"
for every line that was modified .
Sometimes, when a line is removed either by automatic merge or by editing
and no other lines remain in that group, then the text <No src line>
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.
The text "<Merge Conflict>" will appear in the clipboard if you
copy and paste some text containing such a line. But still be careful to
do so.
The "Merge" menu contains some actions that let you select "A", "B" or
"C" everywhere. When you select "Automatically solve simple conflicts" then
KDiff3 restarts the merge and solves as many conflicts as it can. "Set deltas
to conflicts" does the opposite: Even simple conflicts have to be solved
manually then. For all these actions the manual selections that happened
before are lost. (KDiff3 will tell you so, before proceeding.)
Navigation And Editing
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.
You can also use the wheel mouse to scroll up and down.
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.)
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
above, see Merging).
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".
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- & 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.
Select, Copy And Paste
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.
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.
"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.
Saving
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.)
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.
Finding Strings
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.
Options
Options and the recent-file-list will be saved when you exit the program,
and reloaded when you start it. (Menu Settings->Configure KDiff3 ...)
Font
Select a fixed width font. (On some systems this dialog will also
present variable width fonts, but you should not use them.)
- Italic Font for Deltas: 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.
Colors
- Foreground color: Usually black.
- Background color: Usually white.
- Diff Background color: Usually light gray.
- Color A: Usually dark blue.
- Color B: Usually dark green.
- Color C: Usually dark magenta.
- Conflict Color: Usually red.
- Current range background color: Usually light yellow.
- Current range diff background color:Usually dark yellow.
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.
Editor Settings
- Tab inserts spaces: If this is disabled and you press the
tabulator key, a tab-character is inserted, otherwise the appropriate
amount of characters is inserted.
- Tab size: Can be adjusted for your specific needs. Default
is 8.
- Auto indentation: When pressing Enter or Return the indentation
of the previous line is used for the new line.
- Auto copy selection: Every selection is immediately copied
to the clipboard when active and you needn't explicitely copy it.
Diff & Merge Settings
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.
- Ignore white space: Default is on. White space will be
ignored in the first part of the analysis in which the line matching is
done. In the result the white space differences will be shown nevertheless.
- Preserve Carriage Return: 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.
Ignore numbers: 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.
Convert to Upper Case: Default is off. Converts the input to upper case
while reading. Hence the comparison is not case sensitive. Take care during merging
because the case information will be lost in the merge-result too.
Preprocessor-Command:
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.
Line-Matching Preprocessor-Command:
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.
- Use external diff:If you have an external diff-tool (e.g. GNU-diff)
you can use it for the line matching phase. For some complicated files this
might be better than the internal algorithm of KDiff3.
- Try Hard:Passes the "--minimal"-option to the external diff
tool, which then will try hard to find an even smaller delta. This will probably
be effective for complicated and big files. And slow for very big files.
- Ignore trivial matches: Default is on. When trivial lines
match after an difference, this will be ignored and the search for a nontrivial
matching line continues. This improves the results for inputs with empty
lines and lines containing only a open or close-brace character, which is
often the case for C/C++-programs.
- Max search length: Searching for a match is aborted after this
number of lines. The diff might fail for small values but take too long
for big values. Default is 1000.
- Auto Advance Delay (ms): When in auto-advance-mode this setting specifies
how long to show the result of the selection before jumping to the next unsolved
conflict.
Security notice
When running the external diff command or user defined preprocessors (see above),
then KDiff3 creates temporary files and the output of these programs also is sent to
temporary files, which will be read by KDiff3. These files are created in the /tmp-directory
and are readable by anyone. After KDiff3 has read the files and the operation is complete,
KDiff3 deletes them again. Under normal circumstances these files exist only for a
short moment. But a user-definable preprocessor is not guaranteed to terminate. KDiff3
then also hangs and the temporary files won't be deleted.
If your data is very sensitive then don't use the external diff command or user-defined
preprocessors.
Directory Merge
These options are concerned with scanning the directory and handling the
merge: See the Directory Comparison/Merge
Docs for details.
Yet there is one option here that is also relevant for saving single files:
- Backup files: 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.
Miscellaneous
- Show line numbers: You can select if line numbers should be
shows for the input files.
- Show space and tabulator characters for differences: Sometimes
the visible spaces and tabs are disturbing. You can turn this off.
- Show Window A/B/C: Sometimes you want to use the space on
the screen better for long lines. Hide the windows that are not important.
(In the Merge-menu.)
- Start a merge quickly: Sometimes you are viewing the deltas
and decide to merge.
"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.)
Configuring Keyboard-Shortcuts
Currently only the KDE-version supports user-configurable keyboard-shortcuts.
(Menu Settings->Configure Shortcuts...)
Questions And Answers
Why is it called KDiff3?
Tools named KDiff and KDiff2 already exist. Also "KDiff3" should suggest
that it can merge like the "diff3"-tool in the Diff-Tool collection.
Why did I release it under GPL?
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.
Some buttons and functions are missing. What's wrong?
You compiled from source but probably you 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.
Often lines that are similar but not identical appear next to each other
but sometimes not. Why?
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.
Sometimes lines that are identical don't appear next to each other.
Why?
Lines that contain very few (less than three) non-white characters
are not used for a match after a difference. Also solitary matching lines
in the middle of differences are not used for matching if they are too far
apart. Most of the time this behaviour improves the quality of the diff-analysis.
But if users (that includes you!) tell me that they need a different behaviour,
then I'll make this an option in the next version. (Note that when you
use the external diff, this should not happen often.)
Why must all conflicts be solved before the merge result can be saved?
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.
Why does the editor in the merge result window not have an "undo"-function?
This was too much effort to do in the first version. And 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.
When I removed some text, then suddenly "<No src line>" appeared
and can't be deleted. What does that mean and how can one remove this?
For each equal or different section the editor in the merge result
window remembers where it begins or ends. "<No src line>" 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).
Why doesn't KDiff3 support syntax-highlighting?
KDiff3 already uses many colors for difference highlighting. More
highlighting would be confusing. Use another editor for this.
There is so much information here, but your question is still not answered?
Please send me your question. I appreciate every comment.