KDiff3 - Text Diff And Merge Tool

Author: Joachim Eibl
Copyright 2002
Documentation for version 0.81.

KDiff3 is a program that

KDiff3 Home

Screenshots

Documentation

Features

Questions and Answers
 
 
 

Screenshots

This screenshot shows the difference between two text files:

This screenshot shows three input files being merged:

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. I hope that the results are useful for you.
 

Documentation

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.
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. 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 be 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 not appear either if you copy and paste some text containing that line. Be careful to do so!

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.

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 six navigation buttons with which you can jump to the first/last group of lines, to the next/previous difference group or to the next/previous conflict.

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 or Ctrl-C. 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) copies to the clipboard and deletes the selected text and "Paste" (Ctrl-V) inserts the text in the clipboard at the cursorposition or over the current selection.

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

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.

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 Settings

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

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.