diff --git a/doc/en/index.docbook b/doc/en/index.docbook
index 5770710..2519f7e 100644
--- a/doc/en/index.docbook
+++ b/doc/en/index.docbook
@@ -1,2074 +1,2072 @@
KDiff3">
]>
The &kdiff3; HandbookJoachimEibljoachim.eibl at gmx.de2002-2007Joachim Eibl2017Michael Reeves&FDLNotice;2018-04-301.07.00
&kdiff3; is a file and directory diff and merge tool which
compares and merges two or three text input files or directories,shows the differences line by line and character by character(!),provides an automatic merge-facility,has an editor for comfortable solving of merge-conflicts,provides networktransparency via KIO,has options to highlight or hide changes in white-space or comments,supports Unicode, UTF-8 and other file encodings,prints differences,supports version control keyword and history merging.
This document describes &kdiff3;-version 1.7.0.
KDEkdiff3diffmergeCVStriplediffcomparefilesdirectoriesversion controlthree-way-mergein-line-differencessynchronisekpartkionetworktransparenteditorwhite spacecommentsIntroductionYet Another Diff Frontend?
Several graphical diff tools exist. Why choose &kdiff3;? Let me say, why I wrote it.
&kdiff3; started because I had to do a difficult merge. Merging is necessary when several
people work on the same files in a project. A merge can be somewhat automated, when the
merge-tool not only has the new modified files (called "branches"), but also the original file
(called "base"). The merge tool will automatically choose any modification that was only
done in one branch. When several contributors change the same lines, then the merge tool
detects a conflict which must be solved manually.
The merge then was difficult because one contributor had changed many things and corrected
the indentation in many places. Another contributor also had changed much text in the same file,
which resulted in several merge conflicts.
The tool I used then, only showed the changed lines, but not what had changed within these
lines. And there was no information about where only the indentation was changed. The merge
was a little nightmare.
So this was the start. The first version could show differences within a line and showed white space differences.
Later many other features were added to increase the usefulness.
For example if you want to compare some text quickly, then you can copy it to the clipboard and
paste it into either diff window.
A feature that required a big effort was the directory comparison and merge facility, which turned
the program almost into a full file browser.
I hope &kdiff3; works for you too. Have fun!
Joachim Eibl (2003)
Screenshots and FeaturesThis screenshot shows the difference between two text files(Using an early version of &kdiff3;):
3-way-merging is fully supported. This is useful if two people change code independently.
The original file (the base) is used to help &kdiff3; to automatically select the correct
changes.
The merge-editor below the diff-windows allows you to solve conflicts, while showing you the output you will get.
You can even edit the output.
This screenshot shows three input files being merged:
&kdiff3; also helps you to compare and merge complete directories.
This screenshot shows &kdiff3; during a directory merge:
More Features Line-By-Line And Char-By-Char Diff-ViewerBy using the possibilities of a graphical color display &kdiff3; shows
exactly what the difference is. When you have to do many code-reviews, you will like this.
See White-Space Differences At One GlanceSpaces 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. (No more worries when people change the indentation.)
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 ...Fast navigation via buttons.A mouse-click into a summary column sync's all windows to show the same position.Select and copy from any window and paste into the merge result window.Overview column that shows where the changes and conflicts are.The colors are adjustable to your specific preferences.Adjustable Tab size.Option to insert spaces instead of tabs.Open files comfortably via dialog or specify files on the command line.Search for strings in all text windows. Find (Ctrl-F) and Find Next (F3)Show the line numbers for each line. Paste clipboard or drag text into a diff input window.Networktransparency via KIO.Can be used as diff-viewer in KDevelop 3.Word-wrap for long lines.Support for Unicode, UTF-8 and other codecs.Support for right to left languages....File Comparison And MergeCommand-Line OptionsComparing 2 files: kdiff3file1 file2Merging 2 files: kdiff3file1 file2 -m
kdiff3file1 file2 -o outputfileComparing 3 files: kdiff3file1 file2 file3Merging 3 files: kdiff3file1 file2 file3 -m
kdiff3file1 file2 file3 -o outputfile
Note that file1 will be treated as
base of file2 and
file3.
Special case: Files with the same name
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.:
kdiff3dir1/filename dir2 dir3Commandline for starting a directory comparison or merge: This is very similar, but now it's about directories.kdiff3dir1 dir2kdiff3dir1 dir2 -o destdirkdiff3dir1 dir2 dir3kdiff3dir1 dir2 dir3 -o destdirFor directory comparison and merge you can continue to read here.Other command line optionsTo see all available command line options typekdiff3 --help
Example output:
Options:
-m, --merge Merge the input.
-b, --base file Explicit base file. For compatibility with certain tools.
-o, --output file Output file. Implies -m. E.g.: -o newfile.txt
--out file Output file, again. (For compatibility with certain tools.)
--auto No GUI if all conflicts are auto-solvable. (Needs -o file)
--qall Don't solve conflicts automatically. (For compatibility...)
--L1 alias1 Visible name replacement for input file 1 (base).
--L2 alias2 Visible name replacement for input file 2.
--L3 alias3 Visible name replacement for input file 3.
-L, --fname alias Alternative visible name replacement. Supply this once for every input.
--cs string Override a config setting. Use once for every setting. E.g.: --cs "AutoAdvance=1"
--confighelp Show list of config settings and current values.
--config file Use a different config file.
The option allows you to adjust a configuration value that is otherwise only adjustable via the configure dialogs.
But be aware that when &kdiff3; then terminates the changed value will be stored along with the other settings.
With you can find out the names of the available items and current values.Via you can specify a different config file. When you often use &kdiff3;
with completely different setups this allows you to easily switch between them.Ignorable command line optionsMany people want to use &kdiff3; with some version control system.
But when that version control system calls &kdiff3; using command line parameters that &kdiff3; doesn't recognise, then &kdiff3; terminates with an error.
The integration settings allow to specify command line parameters that should be ignored by &kdiff3;.
They will appear in the usage help like in this example:
--foo Ignored. (User defined.)
Command line options to ignore:
A list of options, separated via semicolon ';'. When one of these options appears on the commandline,
then &kdiff3; will ignore it and run without reporting an error.
(Default is "u;query;html;abort").When this isn't enough, then it is recommended to write a shell script that does the option translation.Open-Dialog
Since many input files must be selectable, the program has a special open dialog:
The open dialog allows you to edit the filenames by hand, selecting a file
via the file-browser ("File...") or allows you 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.
You can also select a directory via "Dir...". If for A a directory is specified
then a directory-comparison/merge starts. If A specifies a file but B, C or
the output specify a directory, then &kdiff3; uses the filename from A in the
specified directories.
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.
Paste and Drop Input
Sometimes you want to compare parts of a text that is not an own file. &kdiff3; also
allows you to paste text from the clipboard into the diff input window that has the focus.
The diff analysis happens immediately then.
In the open dialog you need not specify files then, but just close it via "Cancel".
You can also use drag and drop: Drag a file from a file manager
or selected text from an editor and drop it onto a diff input window.
What's the idea? Sometimes a file contains two similar functions, but checking how similar
they really are is a big effort if you first must create two files and then load them. Now
you can simply copy, paste and compare the relevant sections.
Note: Currently you cannot drag anything from &kdiff3;. Only dropping in the diff input
is supported.
Warning: Some editors still interpret the drag and drop into another program like cut
(instead of copy) and paste. Your original data might be lost then.
Comparing Files And Interpreting The Information In The Input WindowsInfo Line
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 editable filename,
a button for browsing, 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.
When you selected another file via browsing or finished editing the filename here
by pressing enter, the new file will be loaded and
compared with the already loaded file(s).
Coloring
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).
This colorscheme is especially useful in the case of three input files, which will be
seen in the next section (Merging).
Summary Column
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. When word-wrap is enabled then this vertical
line appears dotted for wrapped lines.
Overview Column
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.
Manually Aligning Lines
Sometimes the algorithm places the wrong lines next to each other. Or you want to compare
one piece of text with text at a completely different position in the other file.
For these situations you can manually instruct &kdiff3; to align certain lines.
Mark the text for which you want to improve the alignment with the mouse as you would
for copy and paste in the first diff view and then choose "Add Manual Diff Alignment"
in the "Diffview"-menu (keyboard shortcut &Ctrl;Y). An orange bar will appear in
the summary column next to the chosen text. Repeat this for the second and
(if available) third diff view. &kdiff3; will immediately recalculate the differences everytime you do this,
and will align the chosen lines. Of course some of the previously matching lines in between
might not match anymore.
Currently merging doesn't support the use of manual diff help.
Manually Joining and Splitting Diff Sections
In some cases &kdiff3; will see too many or too few diff sections for merging. In such a
case you can join or split existing sections.
Add new sections by first selecting text in the lines that belong together in either input window (as for copying to the clipboard).
Then choose "Split Diff At Selection" in the "Merge" menu.
Splits will be added above the first line and below the last line of the selected text.
If you only want to add one section, then select text beginning at another section-split.
For joining sections in either input window select something in the lines from the sections to join.
(You can join several sections in one step too.) Then choose "Join selected Diffs" in the "Merge"-menu.
Merging And The Merge Output Editor Window
The merge output editor window (below the diff input windows) 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 !!! (Use the "Go
to prev/next unsolved conflicts"-buttons to find the remaining conflicts.)
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.
When B and C are the same, but not the same as A, then C is selected.
The Summary Column
The merge output editor window also has a summary column on the left. 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.
Setting The Current Group And Synchronising Merge And Diff View Position
When clicking into the summary column with the left mouse button in either
window then the beginning of the group belonging to that line will shown in all windows.
This group then becomes the "current group". It is highlighted with the
"Current range (diff) background color" and
a black bar appears on the left side of the text.
Choosing Inputs A, B or C For Current Conflict And Editing
The button bar below the menubar contains three input selector buttons
containing the letters "A", "B" and "C". Click the input selector
button to insert (or remove if already inserted) the lines from the respective source.
To choose the lines from several inputs click the respective buttons in the
needed order. For example if you want that the lines from "B" appear before
the lines from "A" in the output, first click "B", then "A".
If you use the auto-advance option
("Automatically go to next unsolved conflict after source selection"),
you should disable this before choosing lines from several inputs or if you want to
edit the lines after your choice. Otherwise &kdiff3; will jump to the next
conflict after choosing the first input.
It is often helpful directly edit the merge output.
The summary column will show "m" for every line that was manually modified.
When for instance the differences are aligned in a way that simply choosing
the inputs won't be satisfactory, then you can mark the needed text and use
normal copy and paste to put it into the merge output.
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.
Choosing Input A, B, or C for All Conflicts
The normal merge will start by solving simple conflicts automatically.
But the "Merge"-menu provides some actions for other common needs.
If you have to select the same source for most conflicts, then you can
choose "A", "B" or "C" everywhere, or only for the remaining unsolved
conflicts, or for unsolved white space conflicts. If you want to decide every
single delta yourself, you can "Set deltas to conflicts". Or if you want to
return to the automatic choices of &kdiff3; then select
"Automatically solve simple conflicts". &kdiff3; then restarts the merge.
For actions that change your previous modifications &kdiff3; will ask for your
confirmation before proceeding.
Note: When choosing either source for unsolved white space conflicts and
the options "Ignore Numbers" or "Ignore C/C++ Comments" are used then changes in
numbers or comments will be treated like white space too.
Automatic Merge of Version Control Keywords and History (Log)
Many version control systems support special keywords in the file. (e.g. "$Date$",
"$Header$", "$Author$", "$Log$" etc.) During the
check-in the version control system (VCS) changes these lines. For instance
"$Date$" will turn into "$Date: 2005/03/22 18:45:01 $". Since this line will
be different in every version of the file, it would require manual interaction
during the merge.
&kdiff3; offers automatic merge for these items. For simple lines that match the
"Auto merge regular expression"-option in all input-files &kdiff3; will choose
the line from B or - if available - from C. (Additionally it is necessary that the lines
in question line up in the comparison and the previous line contains no conflict.)
This auto merge can either be run immediately after a merge starts (activate the option
"Run regular expression auto merge on merge start") or later via the merge
menu "Run Regular Expression Auto Merge".
Automatic merge for version control history (also called "log") is also supported.
The history automerge can either run immediately when the merge starts by activating the
option "Merge version control history on merge start" or later via the merge menu
"Automatically Solve History Conflicts".
Usually the version control history begins with a line containing the keyword "$Log$".
This must be matched by the "History start regular expression"-option.
&kdiff3; detects which subsequent lines are in the history by analysing the leading characters
that came before the "$Log$"-keyword. If the same "leading comment"-characters also appears in the following
lines, then they are also included in the history.
During each check-in the VCS writes a unique line specifying version-, date- and time-information
followed by lines with user comments.
These lines form one history-entry. This history section grows with every check-in and the
most recent entries appear at the top (after the history start line).
When for parallel development two or more developers check-in a branch of the file then
the merge history will contain several entries that appear as conflicts during the merge
of the branches. Since merging these can become very tedious, &kdiff3; offers support with two
possible strategies: Just insert the history information from both contributors at the top
or sort the history information by a user defined key.
The just-insert-all-entries-method is easier to configure. &kdiff3; just needs a method to
detect, which lines belong to one history entry. Most VCS insert an empty line after each
history entry. If there are no other empty lines, this is a sufficient criterion for &kdiff3;.
Just set an empty "History entry start regular expression". If the empty line criterion
isn't sufficient, you can specify a regular expression to detect the history entry start.
Note that &kdiff3; will remove duplicate history entries. If a history entry appeared several times
in the history of a input file, only one entry will remain in the output.
If you want to sort the history, then you have to specify how the sort key should be built.
Use parentheses in the "History entry start regular expression" to group parts of the regular
expression that should later be used for the sort key.
Then specify the "History entry start sort key order" specifying a comma "," separated list of
numbers referring to the position of the group in the regular expression.
Because this is not so easy to get right immediately, you are able to test and improve
the regular expressions and key-generation in a dedicated dialog by pressing the
"Test your regular expressions"-button.
Example: Assume a history that looks like this:
/**************************************************************************
** HISTORY: $Log: \toms_merge_main_view\MyApplication\src\complexalgorithm.cpp $
**
** \main\integration_branch_12 2 Apr 2001 10:45:41 tom
** Merged branch simon_branch_15.
**
** \main\henry_bugfix_branch_7\1 30 Mar 2001 19:22:05 henry
** Improved the speed for subroutine convertToMesh().
** Fixed crash.
**************************************************************************/
The history start line matches the regular expression ".*\$Log.*\$.*". Then follow
the history entries.
The line with the "$Log$"-keyword begins with two "*" after which follows a space.
&kdiff3; uses the first non-white-space string as "leading comment" and assumes that
the history ends in the first line without this leading comment. In this example the
last line ends with a string that also starts with two "*", but instead of a space
character more "*" follow. Hence this line ends the history.
If history sorting isn't required then the history entry start line regular expression
could look like this. (This line is split in two because it wouldn't fit otherwise.)
\s*\\main\\\S+\s+[0-9]+ (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
[0-9][0-9][0-9][0-9] [0-9][0-9]:[0-9][0-9]:[0-9][0-9]\s+.*
For details about regular expressions please see the
regular expression documentation by Trolltech.
Note that "\s" (with lowercase "s") matches any white space and "\S" (with uppercase "S") matches any non-white-space.
In our example the history entry start contains first the version info with reg. exp. "\\main\\\S+", the date consisting of day "[0-9]+", month "(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" and year "[0-9][0-9][0-9][0-9]", the time "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]" and finally the developers login name ".*".
Note that the "leading comment"-characters (in the example "**") will already be removed by &kdiff3;
before trying to match, hence the regular expression begins with a match for none or more white-space characters "\s*".
Because comment characters can differ in each file (e.g. C/C++ uses other comment characters than a Perl script)
&kdiff3; takes care of the leading comment characters and you should not specify them in the regular expression.
If you require a sorted history. Then the sortkey must be calculated. For this the
relevant parts in the regular expression must be grouped by parentheses.
(The extra parentheses can also stay in if history sorting is disabled.)
\s*\\main\\(\S+)\s+([0-9]+) (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)
([0-9][0-9][0-9][0-9]) ([0-9][0-9]:[0-9][0-9]:[0-9][0-9])\s+(.*)
The parentheses now contain 1. version info, 2. day, 3. month, 4. year, 5. time, 6. name.
But if we want to sort by date and time, we need to construct a key with the elements in a different order of appearance:
First the year, followed by month, day, time, version info and name. Hence the sortkey order to specify is "4,3,2,5,1,6".
Because month names aren't good for sorting ("Apr" would be first) &kdiff3; detects in which order
the month names were given and uses that number instead ("Apr"->"04").
And if a pure number is found it will be transformed to a 4-digit value with leading zeros for sorting.
Finally the resulting sort key for the first history entry start line will be:
2001 04 0002 10:45:41 integration_branch_12 tom
For more information also see Merge Settings.
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
in section "Setting The Current Group And Synchronising Merge And Diff View Position").
The button bar also contains nine navigation buttons with which you can
jump to the current/first/last difference, to the next/previous difference
(ctrl-down/ctrl-up), to the next/previous conflict (ctrl-pgdown/ctrl-pgup),
or to the next/previous unsolved conflict. Note that for &kdiff3; a "conflict"
that was not automatically solved at the start of the merge stays a "conflict"
even if it is solved. Hence the necessity to distinguish "unsolved conflicts".
Auto-Advance
There also is a button "Automatically go to next unsolved conflict after
source selection" (Auto-Advance). If you enable this, then, when one source
is selected, &kdiff3; will jump to and select the next unsolved 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. Before proceeding to the next unsolved conflict
&kdiff3; shows you the effect of your choice for a short time. This delay is
adjustable in the Diff- & Merge-Settings: You can
specify the "Auto-Advance delay" in milli seconds between 0 and 2000. Hint:
Tired of many clicks? - Use a small Auto-Advance-delay and the shortcuts
Ctrl-1/2/3 to select A/B/C for many conflicts.
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.
If the selection exceeds the visible range you can move the mouse over the
window borders which causes &kdiff3; to scroll in that direction.
For very large selections you can also use the navigation keys while holding down
the mouse. E.g. use page up and page down to quickly go to a certain position. At the
end position release the mouse button.
In order to select everything in the current window use menu "Edit"->"Select All" (Ctrl-A).
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 explicitly
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.
"Paste" (Ctrl-V or Shift-Insert) inserts the text in the clipboard at the
cursorposition or over the current selection.
If you paste to either diff input window the contents of the clipboard will
be shown in that window and the comparison will restart immediately. This is
useful if you want to quickly grab a piece of text from somewhere and
compare it with something else without first creating files.
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.)
Line endings are saved according to the normal method on the underlying
operating system. For Unices each line ends with an linefeed-character "\n",
while for Win32-based systems each line ends with a carriage-return + a linefeed
"\r\n". &kdiff3; does not preserve the line-endings of the input files, which
also means that you shouldn't use &kdiff3; with binary files.
Finding Strings
You can search for a string in any text-window of &kdiff3;. The "Find ..."-command
(Ctrl-F) in the Edit-menu opens a dialog that lets you specify the string
to search for. You can also select the windows which should be searched.
Searching will always start at the top. Use the "Find Next"-command (F3)
to proceed to the next occurrence. If you select to search several windows then the first
window will be searched from top to bottom before the search starts in the next
window at the top again, etc.
Printing
&kdiff3; supports printing for textfile differences. The "Print..."-command (Ctrl-P)
in the File-menu opens a dialog that allows you to select the printer and to adjust
other options.
There are several possibilities to adjust the range. Due to different printing
dialogs on different operating systems, the method to achieve certain range selections varies.
All:Print everything.Current:Print a page starting at the first visible line in the window.
(On systems without this option this can be achieved by specifying page number 10000 for printing.)Selection:
Before choosing to print select text with the mouse (like for copy and paste)
in one of the diff input windows to define the start and end line. If no text
in one of the diff input windows was selected, then this won't be an available
choice. (On systems without this option this can be achived by specifying page
number 9999 for printing.)Range:Specify the first and last page.
Other important options for printing will be taken from the normal options:
Font, font sizeShow line numbersWord wrapColorsetc.
Landscape formatting is also recommended for printing.
Options
Options and the recent-file-list will be saved when you exit the program,
and reloaded when you start it. (Menu Settings->Configure &kdiff3; ...)
Font
Select a fixed width font. (On some systems this dialog will also
present variable width fonts, but you should not use them.)
Italic Font for Deltas: If you select this, then text differences
will be drawn with the italic version of the selected font. If the font
doesn't support italic, then this does nothing.ColorsForeground 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.Current range background color: Usually light yellow.Current range diff background color: Usually dark yellow.Color for manually selected diff ranges: Usually orange.Newest file color in directory comparison: Usually green.Oldest file color in directory comparison: Usually red.Middle age file color in directory comparison: Usually dark yellow.Color for missing files in directory comparison: Usually black.
Changing the colors for directory comparison will be effective only when starting the next directory comparison.
On systems with only 16 or 256 colors some colors are not available in pure
form. On such systems the "Defaults"-button will choose a pure color.
Editor SettingsTab 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 explicitly copy it. Line end style: When saving you can select what line
end style you prefer. The default setting is the common choice for the used operating system. 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.
Ignore numbers: Default is off. Number characters ('0'-'9', '.', '-')
will be ignored in the first part of the analysis in which the line matching is
done. In the result the differences will be shown nevertheless, but they are treated
as white space.
Ignore C/C++ comments: Default is off.
Changes in comments will be treated like changes in white space.
Ignore case: Default is off.
Case-differences of characters (like 'A' vs. 'a') will be treated like changes in white space.
Preprocessor-Command:
See next section.
Line-Matching Preprocessor-Command:
See next section.
Try Hard:
Try hard to find an even smaller delta. (Default is on.) This will probably
be effective for complicated and big files. And slow for very big files.
Merge SettingsAuto Advance Delay (ms): When in auto-advance-mode this setting specifies
how long to show the result of the selection before jumping to the next unsolved
conflict.
White space 2/3-file merge default:
Automatically solve all white-space conflict by choosing the specified file.
(Default is manual choice.) Useful if white space really isn't important in many files.
If you need this only occasionally better use "Choose A/B/C For All Unsolved Whitespace Conflicts"
in the merge menu. Note that if you enable either "Ignore numbers" or "Ignore C/C++ comments"
then this auto-choice also applies for conflicts in numbers or comments.
Auto merge regular expression:
Regular expression for lines where &kdiff3; should automatically choose one source. See also Automatic Merge ...
Run regular expression auto merge on merge start:
If activated &kdiff3; runs the automatic merge using the "Auto merge regular expression" when a merge is started.
History start regular expression:
Regular expression for the start of the merge history entry.
Usually this line contains the "$Log$"-keyword.
Default value: ".*\$Log.*\$.*"
History entry start regular expression:
A merge history entry consists of several lines.
Specify the regular expression to detect the first line (without the leading comment).
Use parentheses to group the keys you want to use for sorting.
If left empty, then &kdiff3; assumes that empty lines separate history entries.
See also Automatic Merge ...
History merge sorting:
Enable version control history sorting.
History entry start sort key order:
Each parentheses used in the regular expression for the history start entry
groups a key that can be used for sorting.
Specify the list of keys (that are numbered in order of occurrence
starting with 1) using ',' as separator (e.g. "4,5,6,1,2,3,7").
If left empty, then no sorting will be done.
See also Automatic Merge ...
Merge version control history on merge start:
If activated &kdiff3; runs the automatic history merging using aforementioned options when a merge is started.
Max number of history entries:
&kdiff3; truncates the history list after the specified number of entries. Use -1 to avoid truncation. (Default is -1).
Test your regular expressions
This button shows a dialog that allows you to improve and test the regular expressions above.
Just copy the respective data from your files into the example lines. The "Match results"
will immediately show whether the match succeeds or not.
The "Sort key result" will display the key used for history merge sorting.
Irrelevant merge command:
Specify a command of your own that should be called when &kdiff3; detects
that for a three file merge the file from B doesn't contribute any
relevant data that isn't already contained in the file from C.
The command is called with the three filenames as parameters.
Data matched by the "Auto merge regular expression" or in the
history isn't considered relevant.
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:
Backup files: When a file is saved and an older version already
exists, then the original version will be renamed with an ".orig" extension.
If an old backup file with ".orig" extension already exists then this will
be deleted without backup.
Regional and Language OptionsLanguage:Adjust the language of the user interface. Changing this option doesn't affect the running program. You have to exit and restart &kdiff3; so that the language is changed. (This option is not available in the Frameworks version of &kdiff3;.)
Use the same encoding for everything: The following encoding options can be adjusted separately for each item or if this option is true, all values will take the first value.
Local Encoding:Above the codec-selectors appears a note that tells you what the local encoding is. (This is not adjustable but for your information just in case you don't know your local encoding, but need to select it.)
File Encoding for A/B/C: Adjust the file encoding for input files. This has an effect on how the special characters are interpreted. Since you can adjust each codec separately you can even compare and merge files that were saved using different codecs.
File Encoding for Merge Output and Saving: When you have edited a file, then you can adjust which encoding will be used when saving to disk.
File Encoding for Preprocessor Files:When you define preprocessors then they might not be able to operate on your codec. (e.g.: Your files are 16-bit-unicode and your preprocessor can only take 8-bit-ascii.) With this option you can define the encoding of preprocessor output.
Right To Left Language:Some languages are written right to left. When this option is enabled, &kdiff3; draws the text from right to left in the diff input windows and in the merge output window. Note that if you start &kdiff3; with the command line option "--reverse" then all layouting will be done right to left too. (This is a feature provided by Qt.) This documentation was written assuming that "Right To Left Language" or reverse layout are disabled. So some references to "left" or "right" must be replaced by their respective counterpart if you use these options.
Miscellaneous(These options and actions are available in menus or the buttonbar.)Show line numbers: You can select if line numbers should be
shown for the input files.Show space and tabulator characters for differences: Sometimes
the visible spaces and tabs are disturbing. You can turn this off.Show white space: Turn this off to suppress
any highlighting of white-space-only changes in the text or overview-columns.
(Note that this also applies to changes in numbers or comments if the options "Ignore numbers"
or "Ignore C/C++ comments" are active.)Overview options:
These choices are only available when you compare three files. In normal mode all
differences are shown in one color-coded overview-column. But sometimes you are
especially interested in the differences between only two of these three files.
Selecting "A vs. B", "A vs. C" or "B vs. C"-overview will show a second overview
column with the required information next to the normal overview.
Word wrap diff windows:
Wrap lines when their length would exceed the width of a window.
Show Window A/B/C: Sometimes you want to use the space on
the screen better for long lines. Hide the windows that are not important.
(In the Windows-menu.)Toggle Split Orientation:
Switch between diff windows shown next to each other (A left of B left of C) or above
each other (A above B above C). This should also help for long lines. (In the Windows-menu.)
Start a merge quickly:
Sometimes you are viewing the deltas and decide to merge.
"Merge current file" in the Directory-menu also works if you only compare
two files. A single click starts the merge and uses the filename of the last
input-file as the default output filename. (When this is used to restart
a merge, then the output filename will be preserved.)Configuring Keyboard-Shortcuts
Currently only the Frameworks-version supports user-configurable keyboard-shortcuts.
(Menu Settings->Configure Shortcuts...)
Preprocessor Commands
&kdiff3; supports two preprocessor options.
Preprocessor-Command:
When any file is read, it will be piped through this external command.
The output of this command will be visible instead of the original file.
You can write your own preprocessor that fulfills your specific needs.
Use this to cut away disturbing parts of the file, or to automatically
correct the indentation etc.
Line-Matching Preprocessor-Command:
When any file is read, it will be piped through this external command. If
a preprocessor-command (see above) is also specified, then the output of the
preprocessor is the input of the line-matching preprocessor.
The output will only be used during the line matching phase of the analysis.
You can write your own preprocessor that fulfills your specific needs.
Each input line must have a corresponding output line.
The idea is to allow the user greater flexibility while configuring the diff-result.
But this requires an external program, and many users don't want to write one themselves.
The good news is that very often sed or perl
will do the job.
Example: Simple testcase: Consider file a.txt (6 lines):
aa
ba
ca
da
ea
fa
And file b.txt (3 lines):
cg
dg
eg
Without a preprocessor the following lines would be placed next to each other:
aa - cg
ba - dg
ca - eg
da
ea
fa
This is probably not wanted since the first letter contains the actually interesting information.
To help the matching algorithm to ignore the second letter we can use a line matching preprocessor
command, that replaces 'g' with 'a':
sed 's/g/a/'
With this command the result of the comparison would be:
aa
ba
ca - cg
da - dg
ea - eg
fa
Internally the matching algorithm sees the files after running the line matching preprocessor,
but on the screen the file is unchanged. (The normal preprocessor would change the data also on
the screen.)
sed Basics
This section only introduces some very basic features of sed. For more
information see info:/sed or
http://www.gnu.org/software/sed/manual/html_mono/sed.html.
A precompiled version for Windows can be found at
http://unxutils.sourceforge.net.
Note that the following examples assume that the sed-command is in some
directory in the PATH-environment variable. If this is not the case, you have to specify the full absolute
path for the command.
In this context only the sed-substitute-command is used:
sed 's/REGEXP/REPLACEMENT/FLAGS'
Before you use a new command within &kdiff3;, you should first test it in a console.
Here the echo-command is useful. Example:
echo abrakadabra | sed 's/a/o/'
-> obrakadabra
This example shows a very simple sed-command that replaces the first occurance
of "a" with "o". If you want to replace all occurances then you need the "g"-flag:
echo abrakadabra | sed 's/a/o/g'
-> obrokodobro
The "|"-symbol is the pipe-command that transfers the output of the previous
command to the input of the following command. If you want to test with a longer file
then you can use cat on Unix-like systems or type
on Windows-like systems. sed will do the substitution for each line.
catfilename | sedoptionsExamples For sed-Use In &kdiff3;Ignoring Other Types Of Comments
Currently &kdiff3; understands only C/C++ comments. Using the
Line-Matching-Preprocessor-Command you can also ignore
other types of comments, by converting them into C/C++-comments.
Example: To ignore comments starting with "#", you would like to convert them
to "//". Note that you also must enable the "Ignore C/C++-Comments" option to get
an effect. An appropriate Line-Matching-Preprocessor-Command would be:
sed 's/#/\/\//'
Since for sed the "/"-character has a special meaning, it is necessary to place the
"\"-character before each "/" in the replacement-string. Sometimes the "\" is required
-to add or remove a special meaning of certain characters. The single quotation marks (') before
-and after the substitution-command are important now, because otherwise the shell will
-try to interpret some special characters like '#', '$' or '\' before passing them to
-sed. Note that on Windows you will need the double quotation marks (") here. Windows
-substitutes other characters like '%', so you might have to experiment a little bit.
+to add or remove a special meaning of certain characters. The single quotation marks (') are only important
+when testing on the command shell as it will otherwise attempt to process some characters.
+KDiff3 does not do this except for the escape sequences '\"' and '\\'.
Caseinsensitive Diff
Use the following Line-Matching-Preprocessor-Command to convert all input to uppercase:
sed 's/\(.*\)/\U\1/'
Here the ".*" is a regular expression that matches any string and in this context matches
all characters in the line.
The "\1" in the replacement string refers to the matched text within the first pair of "\(" and "\)".
The "\U" converts the inserted text to uppercase.
Ignoring Version Control Keywords
CVS and other version control systems use several keywords to insert automatically
generated strings (info:/cvs/Keyword substitution).
All of them follow the pattern "$KEYWORD generated text$". We now need a
Line-Matching-Preprocessor-Command that removes only the generated text:
sed 's/\$\(Revision\|Author\|Log\|Header\|Date\).*\$/\$\1\$/'
The "\|" separates the possible keywords. You might want to modify this list
according to your needs.
The "\" before the "$" is necessary because otherwise the "$" matches the end of the line.
While experimenting with sed you might come to understand and even like
these regular expressions. They are useful because there are many other programs that also
support similar things.
Ignoring Numbers
Ignoring numbers actually is a built-in option. But as another example, this is how
it would look as a Line-Matching-Preprocessor-command.
sed 's/[0123456789.-]//g'
Any character within '[' and ']' is a match and will be replaced with nothing.
Ignoring Certain Columns
Sometimes a text is very strictly formatted, and contains columns that you always want to ignore, while there are
other columns you want to preserve for analysis. In the following example the first five columns (characters) are
ignored, the next ten columns are preserved, then again five columns are ignored and the rest of the line is preserved.
sed 's/.....\(..........\).....\(.*\)/\1\2/'
Each dot '.' matches any single character. The "\1" and "\2" in the replacement string refer to the matched text within the first
and second pair of "\(" and "\)" denoting the text to be preserved.
Combining Several Substitutions
Sometimes you want to apply several substitutions at once. You can then use the
semicolon ';' to separate these from each other. Example:
echo abrakadabra | sed 's/a/o/g;s/\(.*\)/\U\1/'
-> OBROKODOBRO
Using perl instead of sed
Instead of sed you might want to use something else like
perl.
perl -p -e 's/REGEXP/REPLACEMENT/FLAGS'
But some details are different in perl. Note that where
sed needed "\(" and "\)" perl
requires the simpler "(" and ")" without preceding '\'. Example:
sed 's/\(.*\)/\U\1/'
perl -p -e 's/(.*)/\U\1/'
Order Of Preprocessor Execution
The data is piped through all internal and external preprocessors in the
following order:
Normal preprocessor,Line-Matching-Preprocessor,Ignore case (conversion to uppercase),Detection of C/C++ comments,Ignore numbers,Ignore white space
The data after the normal preprocessor will be preserved for display and merging. The
other operations only modify the data that the line-matching-diff-algorithm sees.
In the rare cases where you use a normal preprocessor note that
the line-matching-preprocessor sees the output of the normal preprocessor as input.
Warning
The preprocessor-commands are often very useful, but as with any option that modifies
your texts or hides away certain differences automatically, you might accidentally overlook
certain differences and in the worst case destroy important data.
For this reason during a merge if a normal preprocessor-command is being used &kdiff3;
will tell you so and ask you if it should be disabled or not.
But it won't warn you if a Line-Matching-Preprocessor-command is active. The merge will not complete until
all conflicts are solved. If you disabled "Show White Space" then the differences that
were removed with the Line-Matching-Preprocessor-command will also be invisible. If the
Save-button remains disabled during a merge (because of remaining conflicts), make sure to enable
"Show White Space". If you don't want to merge these less important differences manually
you can select "Choose [A|B|C] For All Unsolved White space Conflicts" in the Merge-menu.
Directory Comparison and Merge with &kdiff3;Introduction into Directory Comparison and Merge
Often programmers must modify many files in a directory to achieve their
purpose. For this &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.