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