Directory Comparison and Merge with KDiff3


Author of KDiff3 and of this documentation: Joachim Eibl
Copyright (C) 2003

Screenshot

Text diff documentation

Contents:

Introduction

Often programmers must modify many files in a directory to achieve their purpose. Now KDiff3 also lets you compare and merge complete directories recursively!

Even though comparing and merging directories seems to be quite obvious, there are several details that you should know about. Most important is of course the fact that now many files might be affected by each operation. If you don't have backups of your original data, then it can be very hard or even impossible to return to the original state. So before starting a merge, make sure that your data is safe, and going back is possible. If you make an archive or use some version control system is your decision, but even experienced programmers and integrators need the old sources now and then. And note that even though I (the author of KDiff3) try to do my best, I can't guarantee that there are no bugs. According to the GNU-GPL there is NO WARRANTY whatsoever for this program. So be humble and always keep in mind:

To err is human, but to really mess things up you need a computer.


So this is what this program can do for you: KDiff3 ...

Comparing And Merging Two Or Three Directories

Starting Directory Comparison

This is very similar to the single file merge and comparison. You just have to specify directories only on the command line or in the file-open dialog.
Commandline examples:
kdiff3 dir1 dir2 Compare/Merge two directories
kdiff3 dir1 dir2 dir3 Compare/Merge three directories. (dir1 is the base, dir3 is the destination dir for the merge)
kdiff3 dir1 dir2 -o destdir Compare/Merge two directories, with the merge result written to destdir.
kdiff3 dir1 dir2 dir3 -o destdir Compare/Merge three directories, with the merge result written to destdir.

Note that a merge does not start automatically. For this you first must select a menu entry or the key F5. (More details later.)

While reading the directories a message-box appears that informs you of the progress. If you abort the directory scan, then all files that have been compared until then will be listed.

When the directory scan is complete then KDiff3 will show a listbox with the results left, ...
Image of the directory browser.

... and details about the currently selected item on the right:
Image with information about the selected item.

The Name Column

Each file and directory that was found during the scan is shown here in a tree. You can select an item by clicking it with the mouse once.
The directories are collapsed by default. You can expand and collapse them  by clicking on the "+"/"-" or by double-clicking the item or by using the left/right-arrow-keys.
If you double-click a file item then the file comparison starts and the file-diff-window will appear.
The image  in the name column reflects the file type in the first directory ("A"). It can be one of these:
If the file type is different in the other directories, then this is visible in the columns A/B/C and in the window that shows the details about the selected item. Note that for such a case no merge operation can be selected automatically. When starting the merge, then the user will be informed of problems of that kind.

The Columns A/B/C and the Coloring Scheme

As can be seen in the image above the colors red, green, yellow and black are used in the columns A/B/C.
But for items that were identical in the comparison their color also is identical even if the age is not.
Since the age of items in directories can vary, depending on the item, only the previous sentence holds. The age of a directory is not considered for the color.

If the item in the directory is a link then a link-arrow will be drawn on it. If it is an directory, then the directory image will be shown in the respective color.

The idea for this coloring scheme I came upon in dirdiff. The colors resemble the colors of a leaf that is green when new, turns yellow later and red when old.

The Operation Column

After comparing the directories KDiff3 also evaluates a proposal for a merge operation. This is shown in the "Operation" column. You can modify the operation by clicking on the operation you want to change. A small menu will popup and allows you to select an operation for that item. This operation will be executed during the merge. It depends on the item and on the merge-mode you are in, what operations are available. The merge-mode is one of
In three directory merge the operation proposal will be: If for an item ...

In two directory merge the operation proposal will be: If for an item ...
Sync-mode is active if only two directories and no explicit destination were specified and if the option "Synchronize directories" is active. KDiff3 then selects a default operation so that both directories are the same afterwards. If for an item ...
When two directories are merged and the option "Copy newer instead of merging" is selected, then KDiff3 looks at the dates and proposes to choose the newer file. If the files are not equal but have equal dates, then the operation will contain "Error: Dates are equal but files are not." While such items exist the directory merge cannot start.

The Status Column

During the merge one file after the other will be processed. The status column will show "Done" for items where the merge operation has succeeded, and other texts if something unexpected happened. When a merge is complete, then you should make a last check to see if the status for all items is agreeable.

Doing A Merge

When you have made all your operation choices (in all subdirectories too) then you can start the merge.

Be aware that if you didn't specify a destination directory explicitely, then the destination will be "C" in three directory mode, "B" in two directory merge mode, and in sync-mode it will be "A" or/and "B".

If you have specified a destination directory also check that all items that should be in the output, are in the tree. There are some options that allow that certain items are not put into the tree. Check these options to avoid unpleasant surprises:
(In the current version, you must do a rescan yourself, after changing  options affecting the directory scan.)

If you are satisfied so far, the rest is easy.
In the "Directory"-menu select "Start/Continue directory merge" or press F5 (which is the shortcut).
If due to conflicting filetypes still some items with invalid operations exist, then a messagebox will appear and these items will be pointed out, so you can select a valid operation for the item.
Otherwise a dialog will appear giving you the options "Do it", "Simulate it" and "Cancel".
Then KDiff3 will run the specified operation for all items. If manual interaction is required (single file merge), then a merge window will open (see the big image).
When you have finished with a file, again select "Start/Continue directory merge" or the key F5. If you haven't saved yet, a dialog will ask you to do so. Then KDiff3 will continues with the next item.

When KDiff3 encounters an error, it will tell you so and will show the verbose-status-information. At the bottom of this list, there will be some error messages, that should help you to understand the cause of the problem. When you continue merging (F5 key) KDiff3 will give you the choice to retry or skip the item that caused the problem. This means that before continuing you can choose another operation or solve the problem by other means.

When the merge is complete, then KDiff3 will inform you via a message box.

Options for Comparing and Merging Directories

The KDiff3-preferences (menu "Settings"->"Configure KDiff3") now has a section called "Directory Merge" with these options:

Other Functions

Split/Full Screen Mode
Usually the directory merge list view remains visible while a single file is compared or merged. With the mouse you can move the the splitter bar that separates the file list from the text-diff windows. If you don't want this, you can disable "Split Screen View" in the "Directory"-menu. Then you can use "Toggle View" in the "Directory"-menu to switch between the file list and the text-diff view that then occupy the full screen.

Comparing or Merging a Single File
Probably you will prefer a simple double mouse click on a file in order to compare it. Nevertheless there also exists an entry in the "Directory"-menu. You can also directly merge a single file, without starting the directory merge via the "Merge single file" in the "Directory"-Menu. On saving the result, the status will be set to done, and the file will not be merged again if a directory merge is started.

But note that this status information will be lost when you rerun a directory scan: "Directory"-menu: "Rescan"