# The &komparator; Handbook

## Introduction

&komparator; is a &kde; application that allows the user to search two directories and synchronize them interactively. Unlike other (command line) tools the user has intuitive control over what is done.

An easy way to get help about &komparator; is the "What's this" help option. First enable this help by clicking on the ? in the title bar, or hit the What's this button at the bottom of the GUI. Then click on the item that you want to have information about.

## Using &komparator;

Before starting to search, you need at least specify the two folders that you want to compare. The terms "left" and "right" refer to the positions of the file lists in the Newer files and Missing files tabs. The selection of the URLs is done in the URL selection boxes. They accept drops from konqueror or other applications where you can drag URLs from. Valid URLs are absolute paths like `/path/to/your/directory` and kioslave objects like `media:/sda1` or `ftp://ftp.yourserver.com`. Non-local files will be downloaded to calculate their MD5 checksum or perform binary comparison. URL boxes URL boxes The virtual subfolders behave as if they were linked inside the right URL. For example, the right URL `/path/to/your/directory` with the virtual subfolder `/path/to/virtual/subfolder` will behave as if you were searching the folder `/path/to/your/directory` with a subfolder `/path/to/your/directory/subfolder`. The folder `/path/to/your/directory/subfolder` should not exist in reality, as all file actions will only be performed on the virtual subfolder. It is also a bad idea to use real subfolders as virtual subfolders. This option is useful, if you want to create a backup of several different folders into one single backup folder.

Apart from this, you can specify various search/compare options and general settings:

### Basic search options

Basic search options Basic search options

#### Search Options

##### Include subfolders

If checked, files in subfolders are also found. Soft-linked directories are only searched, if Follow soft links is enabled.

##### Include hidden items

If checked, all files will be displayed. Otherwise all hidden files, and files, that are in a hidden subfolder (relative to the folder you are comparing), will be excluded from the search.

##### Use file index

This options allows you to use locate to find files instead of the internal search. Usually this is faster if there are very many files. Only files that are in the current database are found. Update it regularly with updatedb (this is usually done by a cron job).

##### Case sensitive search

If enabled the regular expression provided in the Extended Search Options tab will be taken exactly as they are. Otherwise [a-d]*[^1-3] equals [a-dA-D]*[^1-3], for example. This affects the comparison of relative paths, too. Therefore a relative path path/to/example_file is not equal to PATH/TO/EXAMPLE_FILE, if this check box is enabled.

##### Find empty folders

If enabled, empty folders will be displayed in the duplicate files list.

##### Follow soft links

If enabled, soft links are considered as the file that they are linked to. This does affect the search for missing / newer files. If a link is copied, in reality the file that it is linked to is copied. The target file's name will be the link's name.

This enables the search within linked directories, too.

#### Duplicate Files Search Options

##### Ignore empty files

If checked, &komparator; won't display empty files as duplicate files. This does not affect whether they are displayed as missing / newer files if necessary.

##### Size comparison

This is enabled by default, so duplicate files are only found by file size comparison, and not by comparison of their paths relative to their parent directories (the directories you are searching).

Disable this to find duplicates only by comparison of relative paths. &komparator; won't be able to detect real duplicates. This is also necessary to show you if a newer / older file pair is not different.

Size comparison is necessary for MD5 checksum and binary comparison to work.

##### Calculate MD5 checksum

If you have a slow system, or many files to search or comparing with a remote folder, it can be useful to turn off the MD5 checksum check. Remote files (=all non-local files, also kioslave protocols other than file://) must be downloaded to temporary files to calculate their checksum. This can take some time, especially if you're connected over a slow network like the internet.

Without MD5 checksum you will find duplicate files that have the same size but are not really equal.

MD5 checksum comparison is necessary for binary comparison.

##### Binary comparison

This will compare the files byte by byte. This can be really slow on large files. Therefore you can set a size threshold for files to be compared. Files that are larger than this threshold are assumed to be equal without real comparison.

##### Duplicates in right URL only

Only search for duplicate files (and empty folders), and only in the right URL. The left URL is not searched at all, and therefore no missing / newer files are reported.

### Extended Search Options

Search options Search options

Only files that match the following specifications are considered during the search.

These settings can have an extreme effect on the search result: If a file exists in both folders, but the newer one is not considered according to your time interval settings, the older file will appear as missing file and you could overwrite the newer file unintentionally.

#### File name contains ... and not ...

The regex fields can be used to narrow the search result down. For example * can be used for a string of any length (also zero length) and ? for exactly one character. For further information about regular expressions please consult your friendly internet. The regular expressions only apply to the file name. All files are reported that match the first expression and at the same time not the second one. If a file name matches both fields, it will be excluded.

##### Regex example

`[a-d]*[^1-3]` will find files that begin with a character a through d, have any length plus 2 (the first and the last character), and don't have the numbers 1 through 3 as the last character.

#### Size

The size input section can be used to find only files that have at least, at most or exactly the spezified size.

1 KB = 1024 Bytes and 1 MB = 1024 KB = 1,048,576 Bytes.

#### Modification or creation time

Here you can select the time interval when the files you want to find were created or modified.

On remote / not *nix file systems, this might not be displayed correctly, as copying can change the modification time on these systems.

You can choose:

- any: No restriction. (default)

- between date x and date y: Files that were created or modified between date x and date y are found (including date x and y).

- during the last z ...: Files that were created or modified during the last z minutes, hours, days, months or years are found, including the current minute, hour, day, month, year.

  ##### Modified during the last ...

  If you are searching on 10th of July for files created or modified during the last 5 days, files from 6th of July are found but not from 5th.

### Settings

Settings Settings

#### Warnings

Show warning dialogs when

- Trashing files

- Deleting files

- Overwriting files when copying files

- Overwriting files when moving files

- Reloading the search result

- Removing a preset

These warnings can also be switched off in the warning dialogs directly.

#### Misc

##### System tray icon

Show an icon in the system tray. If the system tray icon is shown, notifications will appear close to it.

##### Notifications

Show passive notifications, if a user interaction, such as searching, copying or deleting, was completed. These notifications will only appear, if the program window is not the active window (e.g. is minimized or reduced to the system tray icon).

##### Komparator text color theme

Enable komparator text color theme, used to show differences in duplicate files and newer files. Disable it, if you want to use a KDE color theme, that has bad contrast with komparator text colors.

### Preset

Preset Preset

Presets can simplify your life, if you perform a specific kind of search regularly. Choosing a preset will set the gui to the preset's settings. If the preset has empty URLs, the current URLs aren't changed, if it is selected.

You can

- Add a preset: All current settings will be saved as they are. You can choose a name for the preset (that will be displayed in the combo box), and the URLs. If URLs are given, choosing the preset later will set the URL fields to these URLs. If the given URLs are empty, choosing the preset won't change the currently selected URLs.

- Save to the current preset: Overwrite the currently selected preset by the current settings of the GUI. You cannot change the name but the URLs.

- Remove the current preset: Remove the current preset selecting the preset above.

No changes can be done to the default preset.

### Enable/Disable result tab

Enable tab Enable tab

Enable or disable tabs by clicking on the icons. If you don't need the result of one tab, you can disable it to have a slight search speed improvement. Disabling both missing and newer tab (with enabled Size comparison check box) disables the sub path comparison, which will lead to a significant search speed improvement.

### Search button

Search button Search button

When you have made all settings just hit the Search button to start the search. You can cancel the operation at any time. It might take some time to cancel, as &komparator; needs to finish the ongoing sub-process and delete temporary files. If the search has finished, you can clear the search and start a new one.

## Search result

After a successful search and compare operation, &komparator; shows the search result. The duplicates search options, the presets and the find empty folders option are not changable in this stage, as these settings can affect the program's reaction on delete / copy / move events.

Now you can interact with the found files, which can be done in five ways:

- Using the context menu which will appear when you right-click on any file. This is an important way, because some options are only available in this menu: Trash or delete files from the non-reference folder (only in the Duplicate files tab), compare the two selected files (only in the Missing files and the Newer files tabs) and compare the newer files pair (only in the Newer files tab).

- Using the keyboard with the shortcuts Enter or Return for opening selected files, Del to throw the selected files away, Ctrl+Del to delete the selected files and Ctrl+C to copy the selected files (to paste them in konqueror, for example).

- Double click on a file will open it.

- Using the buttons on the GUI. For example, the >> Remove buttons remove the selected files from the list (here from the list on the left), but don't delete them.

- Using drag and drop. This option is only available for missing or newer files, where you can drag files from one side to the other. Holding a Shift button down will move the selected files to the other side, a Control button will copy them. Otherwise you will be asked what to do.

### Duplicate files

Duplicate files tab Duplicate files tab

In the uppermost list view all files that have duplicates are displayed. The filename / path displayed is the one that was found first.

Black colored items are duplicates, that appear in both searched folders and only in them. That means, there are exactly two duplicate files, and both have the same relative path.

Blue colored ones are duplicates by file size (and MD5 checksum and binary comparison), that do not match the restrictions mentioned above.

If one item is selected, all files that are equal will appear in the lower list view (also the file that is listed in the upper list view). Single file interactions done in the upper list view affect only the file that is displayed.

If several files are selected in the upper list view, the last file that was selected is displayed in the lower list view, together with its duplicate files.

If there is only one file in the duplicate list view left, it is removed from the upper list view, because it is no duplicate file any more, and it is displayed in the missing files list. A single empty folder remains until it is deleted.

#### Reference and non-reference folders

The blue / green color of the items in the lower list view is useful to identify which searched folder is the parent of the duplicate file. You can set one of the parent folders (left URL or right URL) as the reference folder (the folder, you want to keep as it is). The other folder is the non-reference folder (the folder, you want to remove duplicate files from). When selecting a new file in the upper list view, the files from the non-reference folder are automatically selected in the lower list view, to make it easier for you to delete them.

You can directly delete all duplicate files of the selected files in the upper list view, that are in the non-reference folder. This option is only available in the context menu (right click on a file to see this menu): Trash non-reference files or Delete non-reference files.

### Missing files

Missing files tab Missing files tab

Here all files are listed that appear only in one folder. The search for missing files is done only be comparing relative paths and file names. Files can be missing in the other folder but - at the same time - be duplicates by file size, and therefore appear in both lists.

You can compare two selected files, if theres exactly one selected file on each side. The file compare dialog is opened by right clicking on one of the selected items and choosing Compare selected files.

### Newer files

Newer files tab Newer files tab

All files that do not appear as duplicate or missing files (or even if they are duplicates but one of them is newer) appear here.

If two relative paths and filenames are equal, but one file is newer than the other, the newer item is colored black and the older one blue.

But the timestamp can be treacherous: On non-local filesystems, the timestamp can be the time when you copied the file, but not when you modified it. On these filesystems you will always find newer files, although they are duplicates. &komparator; will warn you in this case: If the two files are duplicates, the older file will be colored purple instead of blue.

If two files have the same relative path and filename and also the same timestamp, but are different, both files are displayed in red.

The last two color options are only available if you at least enabled Size comparison in the Duplicate Files Search Options.

You can compare two selected files as in the Missing files tab. Additionally, you can compare the two files that have the same relative paths. In this case, only one file may be selected in the current list view.

### Filters

Filters are used to display only files, that match your filter settings. The corresponding counter displays the number of the currently shown items. If not all files are displayed (and some are filtered out), the filter button and the counter have a blue background color:

Filters Filters

Some self-explaining filter options are available in each filter widget:

Missing Files Filter Missing Files Filter

The filter for the duplicate files has two extra options:

- Duplicate files pair: Show all black colored items as explained above.

- Multiple duplicates: Show all blue colored items as explained above.

Duplicate Files Filter Duplicate Files Filter

The filter for newer files has three extra options:

- Real newer files: Show all blue colored items (or the correspondig black colored items) as explained above.

- Newer but equal files: Show all purple colored items (or the correspondig black colored items) as explained.above.

- Different files with same time stamp: Show all red colored items as explained above.

Newer Files Filter Newer Files Filter

## Background information

This chapter intends to give you an overview, how &komparator; works behind the scenes.

### Files search

&komparator; uses the same search engine as KFind. Komparator will have the same (search related) bugs as KFind.

This search engine reports an object that it has found (and that matched user's parameters like regular expressions, ...) to the main program. The main program checks, whether the reported object is a file / link to a file or a folder. If it is a linked folder, it is searched seperately. If this would lead to an infinitive loop (the link points to its parent directory in some way), it is not searched.

If it's a folder and if it is empty, it is stored in memory, if you decided to search for empty folders.

If it's a file (or a symlink, if you decided to "Follow symlinks") it is stored in memory for duplicate / missing / newer file search. If you decided to find empty folders, empty folders are added to duplicates list view now.

### Duplicate files search

In this second step all files found with the search engine are searched for duplicate files.

This is done in the following way: The files are sorted by size; if two files have the same size, an (optional) MD5 checksum and binary comparison is calculated and only if all parameters (size, MD5, bin) were equal, the file is recorded as duplicate of the other one.

### Missing / newer files search

This third step compares the paths + filenames relative to the searched directory.

An example: If you are searching the URLs `/mnt/backup` and `/home/user`, the files `/mnt/backup/emails` and `/home/user/emails` both have the relative file name `./emails` and are therefore equal.

These relative paths + file names are sorted by length, and if they have the same length, they are sorted alphabetically.

Now different possibilities must be considered:

- A file can have no duplicate by relative path + file name, so the file is missing in the other folder.

- It can have a duplicate by file name and one file is newer than the other one. In this case, the files can be real duplicates (and appear in the duplicate list view), but are also shown in the "Newer files" list view.

- It can have a duplicate by file name, but both files have the same timestamp. If the files are equal (checked by MD5 checksum and binary comparison), they are not considered any more, as they were found in the duplicate files search (before).

- If the files have the same file name and timestamp, but are not equal (very unlikely), they are reported in the "Newer files" list view, but marked red to warn the user, that there is something wrong.

## Credits and License

&komparator;

Program copyright 2005-2006 Georg Hennig georg.hennig@web.de

Documentation copyright 2005-2006 Georg Hennig georg.hennig@web.de

&underFDL; &underGPL;

## Installation

### How to obtain &komparator;

&komparator; can be downloaded from the Sourceforge project page.

For news or bug reports visit the &komparator; sourceforge home page.

### Requirements

In order to use &komparator;, you need &kde; 3.4 or higher.

### Compilation and Installation

&install.compile.documentation;
&documentation.index;