KDiff3 - Text Diff And Merge Tool

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

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:

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

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 ("Select...") 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.

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.
 

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

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.

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.)
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) or to the next/previous conflict (ctrl-pgdown/ctrl-pgup).

There also is a button "Automatically go to next conflict after source selection". If you enable this, then, when one source is selected, then KDiff3 will jump to and select the next 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.

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

Options

Options and the recent-file-list will be saved when you exit the program, and reloaded when you start it.

Font

Select a fixed width font. (On some systems this dialog will also present variable width fonts, but you should not use them.)

Colors

Editor Settings

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

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:

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.

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.

Why won't the merge tool automatically merge if both changes are equal?

Previously I also thought this would be nice, but when I tried it, I saw that this is dangerous. Sometimes by coincindence two changes are identical in certain lines but not otherwise. When this is merged automatically then these lines that are actually needed twice - once for each change - only appear once in the merge result. It can even happen that no other conflict appears in the vicinity and then the problem goes completely unnoticed.

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.