joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2: joachim99@2:

KDiff3 - Text Diff And Merge Tool

joachim99@2: Author: Joachim Eibl joachim99@2:
joachim99@2: Copyright 2002
joachim99@2: Documentation for version 0.81.
joachim99@2:
joachim99@2: KDiff3 is a program that
joachim99@2: joachim99@2:

KDiff3 Home joachim99@2:

joachim99@2: joachim99@2:

Screenshots joachim99@2:

joachim99@2: joachim99@2:

Documentation joachim99@2:

joachim99@2: joachim99@2:

Features joachim99@2:

joachim99@2: joachim99@2:

Questions and Answers joachim99@2:
joachim99@2:  
joachim99@2:  
joachim99@2:  

joachim99@2: joachim99@2:

joachim99@2: Screenshots

joachim99@2: This screenshot shows the difference between two text files:
joachim99@2: joachim99@2: joachim99@2:

This screenshot shows three input files being merged:
joachim99@2: joachim99@2:

joachim99@2: joachim99@2:

joachim99@2: Features

joachim99@2: joachim99@2:

Line-By-Line And Char-By-Char Diff-Viewer

joachim99@2: By using the possiblities of a graphical color display KDiff3 shows exactly joachim99@2: what the difference is:
joachim99@2: joachim99@2:
joachim99@2:   joachim99@2:

See White-Space Differences At One Glance

joachim99@2: Spaces and tabs that differ appear visibly. When lines differ only in the joachim99@2: amount of white space this can be seen at one  look in the summary joachim99@2: column on the left side.
joachim99@2: joachim99@2:
joachim99@2:   joachim99@2:

Triple-Diff

joachim99@2: Analyze three files and see where they differ.
joachim99@2: The left/middle/right windows are named A/B/C and have the blue/green/magenta joachim99@2: color respectively.
joachim99@2: If one file is the same and one file is different on a line then the color joachim99@2: shows which file is different. The red color means that both other files are joachim99@2: different.
joachim99@2: joachim99@2:
joachim99@2:   joachim99@2:

Comfortable Merge Of Two Or Three Input Files

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

And ...

joachim99@2: joachim99@2: joachim99@2: joachim99@2:

Diff Algorithm

joachim99@2: Some graphical diff-tools are just front-ends to the good old command-line joachim99@2: Diff. This is reuse at its best but also limits the possiblities of any joachim99@2: front-end because a diff-analysis of each line is not provided by Diff. joachim99@2:

I invented my own diff-algorithm, with the advantage that I could also joachim99@2: reuse it for a line comparison. This algorithm was optimized for use with joachim99@2: C/C++-source files. I hope that the results are useful for you.
joachim99@2:  

joachim99@2: joachim99@2:

joachim99@2: Documentation

joachim99@2: joachim99@2:

Command-Line Options

joachim99@2: - Comparing 2 files:
joachim99@2:                     joachim99@2: kdiff3 file1 file2 joachim99@2:

- Merging 2 files:
joachim99@2:                     joachim99@2: kdiff3 file1 file2 -m
joachim99@2:                     joachim99@2: kdiff3 file1 file2 -o outputfile

joachim99@2: joachim99@2:

- Comparing 3 files:
joachim99@2:                     joachim99@2: kdiff3 file1 file2 file3

joachim99@2: joachim99@2:

- Merging 3 files:
joachim99@2:                     joachim99@2: kdiff3 file1 file2 file3 -m
joachim99@2:                     joachim99@2: kdiff3 file1 file2 file3 -o outputfile
joachim99@2:      Note that file1 will be treated as base of file2 joachim99@2: and file3.

joachim99@2: joachim99@2:

For more information use:
joachim99@2:                     joachim99@2: kdiff3 --help

joachim99@2: joachim99@2:

Open-Dialog

joachim99@2: Since many input files must be selectable, the program has a special open joachim99@2: dialog:
joachim99@2: joachim99@2:
joachim99@2: The open dialog allows to edit the filenames by hand, selecting a file via joachim99@2: the file-browser ("Select...") or allows to choose recent files from the drop-down joachim99@2: lists. If you open the dialog again, then the current names still remain joachim99@2: there. The third  input file is not required. If the entry for "C" remains joachim99@2: empty, then only a two file diff analysis will be done. joachim99@2:

If "Merge" is selected, then the "Output"-line becomes editable. But it joachim99@2: is not required to specify the output filename immediately. You can also postpone joachim99@2: this until saving.

joachim99@2: joachim99@2:

The "Configure"-button opens the options-dialog, so that you can set the joachim99@2: options before running the analysis.
joachim99@2:  

joachim99@2: joachim99@2:

Interpreting The Information In The Input Windows

joachim99@2: At the top of each text window is its "info line". The info lines of the joachim99@2: input windows contain a letter "A", "B" or "C", the filename and the line joachim99@2: number of the first visible line in the window. (Note that window "C" is optional.) joachim99@2: Each info line appears in a different color.
joachim99@2: The three input windows are assigned the letters "A", "B" and "C". "A" has joachim99@2: color blue, "B" has green and "C" has magenta. (These are the defaults, but joachim99@2: can be changed in the Settings-Menu.)
joachim99@2: When a difference is detected then the color shows which input file differs. joachim99@2: When both other input files differ then the color used to express this is joachim99@2: red by default ("Conflict color" in the Settings). joachim99@2:

Left of each text is the "summary column". If differences occurred on joachim99@2: a line then the summary column shows the respective color. For a white-space-only joachim99@2: difference the summary is chequered. For programming languages where white joachim99@2: space is not so important this is useful to see at one glance if anything joachim99@2: of importance was modified. (In C/C++ white space is only interesting within joachim99@2: strings, comments, for the preprocessor, and some only very esoteric situations.) joachim99@2:
joachim99@2: The vertical line separating the summary column and the text is interrupted joachim99@2: if the input file had no lines there.

joachim99@2: joachim99@2:

On the right side a "overview"-column is visible left of the vertical joachim99@2: scrollbar. It shows the compressed summary column of input "A". All the differences joachim99@2: and conflicts are visible at one glance. When only two input windows are used, joachim99@2: then all differences appear red here because every difference is also a conflict. joachim99@2: A black rectangle frames the visible part of the inputs. For very long input joachim99@2: files, when the number of input lines is bigger than the height of the overview joachim99@2: column in pixels, then several input lines share one overview line. A conflict joachim99@2: then has top priority over simple differences, which have priority over no joachim99@2: change, so that no difference or conflict is lost here. By clicking into joachim99@2: this overview column the corresponding text will be shown.
joachim99@2:  

joachim99@2: joachim99@2:

Merging And The Merge Output Editor Window

joachim99@2: This window also has an info line at the top showing "Output:", the filename joachim99@2: and "[Modified]" if you edited something. Usually it will contain some text joachim99@2: through the automatic merge facilities, but often it will also contain conflicts. joachim99@2: joachim99@2:

!!! Saving is disabled until all conflicts are resolved !!!

joachim99@2: joachim99@2:

With only two input files every difference is also a conflict that must joachim99@2: be solved manually.
joachim99@2: With three input files the first file is treated as base, while the second joachim99@2: and third input files contain modifications. When at any line only either joachim99@2: input B or input C have changed but not both then the changed source will joachim99@2: automatically be selected. Only when B and C have changed on the same lines, joachim99@2: then the tool detects a conflict that must be solved manually.

joachim99@2: joachim99@2:

The merge output editor window also has a summary column. It shows the joachim99@2: letter of the input from which a line was selected or nothing if all three joachim99@2: sources where equal on a line. For conflicts it shows a questionmark "?" joachim99@2: and the line shows "<Merge Conflict>", all in red. Because solving joachim99@2: conflicts line by line would take very long, the lines are grouped into joachim99@2: groups that have the same difference and conflict characteristics. When joachim99@2: clicking into the summary column with the left mouse button in either window joachim99@2: then the group belonging to that line will be selected in all windows and joachim99@2: the beginning of that group will be shown. (This might involve an automatic joachim99@2: position jump in the windows if the beginning of a group is not visible.) joachim99@2:
joachim99@2: Note the input selector buttons containing the letters "A", "B" and "C" joachim99@2: in the button bar below the menu bar. When clicking on either input selector joachim99@2: button, the lines from that input will be added at the end of the selected joachim99@2: group if that group didn't contain that source before. Otherwise the lines joachim99@2: from that input will be removed.

joachim99@2: joachim99@2:

Besides, you can directly edit any line. The summary column will show joachim99@2: "m" for every line that was modified .

joachim99@2: joachim99@2:

Sometimes, when a line is removed either by automatic merge or be editing joachim99@2: and no other lines remain in that group, then the text <No src line> joachim99@2: will appear in that line. This is just a placeholder for the group for when joachim99@2: you might change your mind and select some source again. This text won't appear joachim99@2: in the saved file or in any selections you want to copy and paste.

joachim99@2: joachim99@2:

The text "<Merge Conflict>" will not appear either if you copy and joachim99@2: paste some text containing that line. Be careful to do so!

joachim99@2: joachim99@2:

Navigation And Editing

joachim99@2: Much navigation will be done with the scroll bars and the mouse but you joachim99@2: can also navigate with the keys. If you click into either window then you joachim99@2: can use the cursor buttons left, right, up, down, page up, page down, home, joachim99@2: end, ctrl-home, ctrl-end as you would in other programs. The overview-column joachim99@2: next to the  vertical scroll bar of the input files can also be used joachim99@2: for navigating by clicking into it. joachim99@2:

In the merge output editor you can also use the other keys for editing. joachim99@2: You can toggle between insert and overwrite mode with the insert key. (Default joachim99@2: is insert-mode.)

joachim99@2: joachim99@2:

A left-mouse-button-click into any summary column will synchronise all joachim99@2: windows to show the beginning of the same group of lines (as explained above, joachim99@2: see Merging).

joachim99@2: joachim99@2:

The button bar also contains six navigation buttons with which you can joachim99@2: jump to the first/last group of lines, to the next/previous difference group joachim99@2: or to the next/previous conflict.

joachim99@2: joachim99@2:

Select, Copy And Paste

joachim99@2: The input windows don't show a cursor, so selections must be made with joachim99@2: the mouse by clicking with the left mouse button at the start, holding down joachim99@2: the mousebutton and moving to the end, where you release the mouse button joachim99@2: again. You can also select a word by double clicking it. In the merge output joachim99@2: editor you can also select via the keyboard by holding the "shift"-button joachim99@2: and navigation with the cursor keys. joachim99@2:

To copy to the clipboard you must press the "Copy"-button or Ctrl-C. But joachim99@2: there exists an option "Auto Copy Selection". If this is enabled, then whatever joachim99@2: you select is copied immediately and you don't need to explicitely copy. But joachim99@2: pay attention when using this because the contents of the clipboard might joachim99@2: then be destroyed accidentally.

joachim99@2: joachim99@2:

"Cut" (Ctrl-X) copies to the clipboard and deletes the selected text and joachim99@2: "Paste" (Ctrl-V) inserts the text in the clipboard at the cursorposition joachim99@2: or over the current selection.

joachim99@2: joachim99@2:

Options

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

Font

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

Colors

joachim99@2: Foreground color: Usually black.
joachim99@2: Background color: Usually white.
joachim99@2: Diff Background color: Usually light gray.
joachim99@2: Color A: Usually dark blue.
joachim99@2: Color B: Usually dark green.
joachim99@2: Color C: Usually dark magenta.
joachim99@2: Conflict Color: Usually red. joachim99@2:

Editor Settings

joachim99@2: Tab inserts spaces: If this is disabled and you press the tabulator key, joachim99@2: a tab-character is inserted, otherwise the appropriate amount of characters joachim99@2: is inserted.
joachim99@2: Tab size: Can be adjusted for your specific needs. Default is 8.
joachim99@2: Auto indentation: When pressing Enter or Return the indentation of the previous joachim99@2: line is used for the new line.
joachim99@2: Auto copy selection: Every selection is immediately copied to the clipboard joachim99@2: when active and you needn't explicitely copy it. joachim99@2:

Diff Settings

joachim99@2: Ignore white space: Default is on. White space will be ignored in the first joachim99@2: part of the analysis in which the line matching is done. In the result the joachim99@2: white space differences will be shown nevertheless.
joachim99@2: Ignore trivial matches: Default is on. When trivial lines match after an joachim99@2: difference, this will be ignored and the search for a nontrivial matching joachim99@2: line continues. This improves the results for inputs with empty lines and joachim99@2: lines containing only a open or close-brace character, which is often the joachim99@2: case for C/C++-programs.
joachim99@2:  
joachim99@2:   joachim99@2:

joachim99@2: Questions And Answers

joachim99@2: joachim99@2:

Why is it called KDiff3?

joachim99@2: Tools named KDiff and KDiff2 already exist. Also "KDiff3" should suggest joachim99@2: that it can merge like the "diff3"-tool in the Diff-Tool collection. joachim99@2:

Why did I release it under GPL?

joachim99@2: I'm using GPL programs for a very long time now and learned very much by joachim99@2: having a look at many of the sources. Hence this is my "Thank You" to all joachim99@2: programmers that also did so or will do the same. joachim99@2:

Often lines that are similar but not identical appear next to each other joachim99@2: but sometimes not. Why?

joachim99@2: Lines where only the amount of white space characters is different are joachim99@2: treated as "equal" at first, while just one different non-white character joachim99@2: causes the lines to be "different". If similar lines appear next to each joachim99@2: other, this actually is coincidence but this fortunately is often the case. joachim99@2: joachim99@2:

Sometimes lines that are identical don't appear next to each other. Why?

joachim99@2: Lines that contain very few (less than three) non-white characters are joachim99@2: not used for a match after a difference. Also solitary matching lines in joachim99@2: the middle of differences are not used for matching if they are too far apart. joachim99@2: Most of the time this behaviour improves the quality of the diff-analysis. joachim99@2: But if users (that includes you!) tell me that they need a different behaviour, joachim99@2: then I'll make this an option in the next version. joachim99@2:

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

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

Why must all conflicts be solved before the merge result can be saved?

joachim99@2: For each equal or different section the editor in the merge result window joachim99@2: remembers where it begins or ends. This is needed so that conflicts can joachim99@2: be solved manually by simply selecting the source button (A, B or C). This joachim99@2: information is lost while saving as text and it is too much effort to create joachim99@2: a special file format that supports saving and restoring all necessary information. joachim99@2: joachim99@2:

Why does the editor in the merge result window not have an "undo"-function?

joachim99@2: This was too much effort to do in the first version. And you can always joachim99@2: restore a version from one source (A, B or C) by clicking the respective joachim99@2: button. For big editing the use of another editor is recommended anyway. joachim99@2: joachim99@2:

When I removed some text, then suddenly "<No src line>" appeared joachim99@2: and can't be deleted. What does that mean and how can one remove this?

joachim99@2: For each equal or different section the editor in the merge result window joachim99@2: remembers where it begins or ends.  "<No src line>" means that joachim99@2: there is nothing left in a section, not even a new line character. This joachim99@2: can happen either while merging automatically or by editing. This is no problem, joachim99@2: since this hint won't appear in the saved file. If you want the orignal source joachim99@2: back just select the section (click on the left summary column) and then click joachim99@2: the source button with the needed contents (A/B or C). joachim99@2:

Why doesn't KDiff3 support syntax-highlighting?

joachim99@2: KDiff3 already uses many colors for difference highlighting. More highlighting joachim99@2: would be confusing. Use another editor for this.
joachim99@2: joachim99@2:

There is so much information here, but your question is still not answered?

joachim99@2: Please send me your question. I appreciate every comment.
joachim99@2:   joachim99@2: joachim99@2: