KDiff3 - Text Diff And Merge Tool

Author: Joachim Eibl
Copyright 2002-2003
Documentation for version 0.9.60.

KDiff3 is a program that

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:
Screenshot during a merge.

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 ...

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:
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.)

Colors

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

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.

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:

Miscellaneous

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.