Mercurial > hg > easyhg-kdiff3
comparison kdiff3/doc/en/index.html @ 2:53b8ecbce0cb
Initial revision
| author | joachim99 |
|---|---|
| date | Sun, 18 Aug 2002 16:23:32 +0000 |
| parents | |
| children |
comparison
equal
deleted
inserted
replaced
| 1:391d4ae068d9 | 2:53b8ecbce0cb |
|---|---|
| 1 <!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> | |
| 2 <html> | |
| 3 <head> | |
| 4 | |
| 5 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| 6 | |
| 7 <meta name="GENERATOR" content="Mozilla/4.78 [de] (X11; U; Linux 2.4.10-4GB i686) [Netscape]"> | |
| 8 </head> | |
| 9 <body background="background.png"> | |
| 10 | |
| 11 <h1> KDiff3 - Text Diff And Merge Tool</h1> | |
| 12 Author: <a href="mailto:joachim.eibl@gmx.de">Joachim Eibl</a> | |
| 13 <br> | |
| 14 Copyright 2002 <br> | |
| 15 Documentation for version 0.81.<br> | |
| 16 <br> | |
| 17 KDiff3 is a program that<br> | |
| 18 <ul> | |
| 19 <li>compares two or three text input files,</li> | |
| 20 <li>shows the differences line by line and character by character (!),</li> | |
| 21 <li>provides an automatic merge-facility and</li> | |
| 22 <li>an editor for comfortable solving of merge-conflicts</li> | |
| 23 <li>and has an intuitive graphical user interface.</li> | |
| 24 </ul> | |
| 25 <p><a href="http://kdiff3.sourceforge.net">KDiff3 Home</a> | |
| 26 </p> | |
| 27 | |
| 28 <p><a href="#screenshots">Screenshots</a> | |
| 29 </p> | |
| 30 | |
| 31 <p><a href="#documentation">Documentation</a> | |
| 32 </p> | |
| 33 | |
| 34 <p><a href="#features">Features</a> | |
| 35 </p> | |
| 36 | |
| 37 <p><a href="#faq">Questions and Answers</a> | |
| 38 <br> | |
| 39 <br> | |
| 40 <br> | |
| 41 </p> | |
| 42 | |
| 43 <h2> <a name="screenshots"></a> | |
| 44 Screenshots</h2> | |
| 45 This screenshot shows the difference between two text files: <br> | |
| 46 <img src="screenshot_diff.png" height="269" width="578"> | |
| 47 | |
| 48 <p>This screenshot shows three input files being merged: <br> | |
| 49 <img src="screenshot_merge.png" height="306" width="577"> | |
| 50 </p> | |
| 51 | |
| 52 <h2> <a name="features"></a> | |
| 53 Features</h2> | |
| 54 | |
| 55 <h3> Line-By-Line And Char-By-Char Diff-Viewer</h3> | |
| 56 By using the possiblities of a graphical color display KDiff3 shows exactly | |
| 57 what the difference is: <br> | |
| 58 <img src="letter_by_letter.png" height="63" width="490"> | |
| 59 <br> | |
| 60 | |
| 61 <h3> See White-Space Differences At One Glance</h3> | |
| 62 Spaces and tabs that differ appear visibly. When lines differ only in the | |
| 63 amount of white space this can be seen at one look in the summary | |
| 64 column on the left side. <br> | |
| 65 <img src="white_space.png" height="60" width="480"> | |
| 66 <br> | |
| 67 | |
| 68 <h3> Triple-Diff</h3> | |
| 69 Analyze three files and see where they differ. <br> | |
| 70 The left/middle/right windows are named A/B/C and have the blue/green/magenta | |
| 71 color respectively. <br> | |
| 72 If one file is the same and one file is different on a line then the color | |
| 73 shows which file is different. The red color means that both other files are | |
| 74 different. <br> | |
| 75 <img src="triple_diff.png" height="50" width="512"> | |
| 76 <br> | |
| 77 | |
| 78 <h3> Comfortable Merge Of Two Or Three Input Files</h3> | |
| 79 KDiff3 can be used to merge two or three input files and automatically | |
| 80 merges as much as possible. The result is presented in an editable window | |
| 81 where most conflicts can be solved with a single mouseclick: Select the buttons | |
| 82 A/B/C from the button-bar to select the source that should be used. You can | |
| 83 also select more than one source. Since this output window is an editor even | |
| 84 conflicts which need further corrections can be solved here without requiring | |
| 85 another tool. <br> | |
| 86 | |
| 87 <h3> And ...</h3> | |
| 88 | |
| 89 <ul> | |
| 90 <li> Fast navigation via buttons.</li> | |
| 91 <li>A mouse-click into a summary column sync's all windows to show | |
| 92 the same position.</li> | |
| 93 <li> Select and copy from any window and paste into the merge result window.</li> | |
| 94 <li> Overview column that shows where the changes and conflicts are.</li> | |
| 95 <li> The colors are adjustable to your specific preferences.</li> | |
| 96 <li> Adjustable Tab size. </li> | |
| 97 <li>Option to insert spaces instead of tabs.</li> | |
| 98 <li> Open files comfortably via dialog or specify files on the command | |
| 99 line.</li> | |
| 100 <li> ...</li> | |
| 101 | |
| 102 </ul> | |
| 103 | |
| 104 <h3> Diff Algorithm</h3> | |
| 105 Some graphical diff-tools are just front-ends to the good old command-line | |
| 106 Diff. This is reuse at its best but also limits the possiblities of any | |
| 107 front-end because a diff-analysis of each line is not provided by Diff. | |
| 108 <p>I invented my own diff-algorithm, with the advantage that I could also | |
| 109 reuse it for a line comparison. This algorithm was optimized for use with | |
| 110 C/C++-source files. I hope that the results are useful for you. <br> | |
| 111 </p> | |
| 112 | |
| 113 <h2> <a name="documentation"></a> | |
| 114 Documentation</h2> | |
| 115 | |
| 116 <h3> Command-Line Options</h3> | |
| 117 - Comparing 2 files: <br> | |
| 118 <tt> | |
| 119 kdiff3 <i>file1 file2</i></tt> | |
| 120 <p>- Merging 2 files: <br> | |
| 121 <tt> | |
| 122 kdiff3 <i>file1 file2</i> -m</tt> <br> | |
| 123 <tt> | |
| 124 kdiff3 <i>file1 file2</i> -o <i>outputfile</i></tt> </p> | |
| 125 | |
| 126 <p>- Comparing 3 files: <br> | |
| 127 <tt> | |
| 128 kdiff3 <i>file1 file2 file3</i></tt> </p> | |
| 129 | |
| 130 <p>- Merging 3 files: <br> | |
| 131 <tt> | |
| 132 kdiff3 <i>file1 file2 file3</i> -m</tt> <br> | |
| 133 <tt> | |
| 134 kdiff3 <i>file1 file2 file3</i> -o <i>outputfile</i></tt><i> </i><br> | |
| 135 Note that file1 will be treated as base of file2 | |
| 136 and file3. </p> | |
| 137 | |
| 138 <p>For more information use: <br> | |
| 139 <tt> | |
| 140 kdiff3 --help</tt> </p> | |
| 141 | |
| 142 <h3> Open-Dialog</h3> | |
| 143 Since many input files must be selectable, the program has a special open | |
| 144 dialog: <br> | |
| 145 <img src="open_dialog.png" height="189" width="448"> | |
| 146 <br> | |
| 147 The open dialog allows to edit the filenames by hand, selecting a file via | |
| 148 the file-browser ("Select...") or allows to choose recent files from the drop-down | |
| 149 lists. If you open the dialog again, then the current names still remain | |
| 150 there. The third input file is not required. If the entry for "C" remains | |
| 151 empty, then only a two file diff analysis will be done. | |
| 152 <p>If "Merge" is selected, then the "Output"-line becomes editable. But it | |
| 153 is not required to specify the output filename immediately. You can also postpone | |
| 154 this until saving. </p> | |
| 155 | |
| 156 <p>The "Configure"-button opens the options-dialog, so that you can set the | |
| 157 options before running the analysis. <br> | |
| 158 </p> | |
| 159 | |
| 160 <h3> Interpreting The Information In The Input Windows</h3> | |
| 161 At the top of each text window is its "info line". The info lines of the | |
| 162 input windows contain a letter "A", "B" or "C", the filename and the line | |
| 163 number of the first visible line in the window. (Note that window "C" is optional.) | |
| 164 Each info line appears in a different color. <br> | |
| 165 The three input windows are assigned the letters "A", "B" and "C". "A" has | |
| 166 color blue, "B" has green and "C" has magenta. (These are the defaults, but | |
| 167 can be changed in the Settings-Menu.) <br> | |
| 168 When a difference is detected then the color shows which input file differs. | |
| 169 When both other input files differ then the color used to express this is | |
| 170 red by default ("Conflict color" in the Settings). | |
| 171 <p>Left of each text is the "summary column". If differences occurred on | |
| 172 a line then the summary column shows the respective color. For a white-space-only | |
| 173 difference the summary is chequered. For programming languages where white | |
| 174 space is not so important this is useful to see at one glance if anything | |
| 175 of importance was modified. (In C/C++ white space is only interesting within | |
| 176 strings, comments, for the preprocessor, and some only very esoteric situations.) | |
| 177 <br> | |
| 178 The vertical line separating the summary column and the text is interrupted | |
| 179 if the input file had no lines there. </p> | |
| 180 | |
| 181 <p>On the right side a "overview"-column is visible left of the vertical | |
| 182 scrollbar. It shows the compressed summary column of input "A". All the differences | |
| 183 and conflicts are visible at one glance. When only two input windows are used, | |
| 184 then all differences appear red here because every difference is also a conflict. | |
| 185 A black rectangle frames the visible part of the inputs. For very long input | |
| 186 files, when the number of input lines is bigger than the height of the overview | |
| 187 column in pixels, then several input lines share one overview line. A conflict | |
| 188 then has top priority over simple differences, which have priority over no | |
| 189 change, so that no difference or conflict is lost here. By clicking into | |
| 190 this overview column the corresponding text will be shown.<br> | |
| 191 </p> | |
| 192 | |
| 193 <h3> Merging And The Merge Output Editor Window</h3> | |
| 194 This window also has an info line at the top showing "Output:", the filename | |
| 195 and "[Modified]" if you edited something. Usually it will contain some text | |
| 196 through the automatic merge facilities, but often it will also contain conflicts. | |
| 197 | |
| 198 <p>!!! Saving is disabled until all conflicts are resolved !!! </p> | |
| 199 | |
| 200 <p>With only two input files every difference is also a conflict that must | |
| 201 be solved manually. <br> | |
| 202 With three input files the first file is treated as base, while the second | |
| 203 and third input files contain modifications. When at any line only either | |
| 204 input B or input C have changed but not both then the changed source will | |
| 205 automatically be selected. Only when B and C have changed on the same lines, | |
| 206 then the tool detects a conflict that must be solved manually. </p> | |
| 207 | |
| 208 <p>The merge output editor window also has a summary column. It shows the | |
| 209 letter of the input from which a line was selected or nothing if all three | |
| 210 sources where equal on a line. For conflicts it shows a questionmark "?" | |
| 211 and the line shows "<Merge Conflict>", all in red. Because solving | |
| 212 conflicts line by line would take very long, the lines are grouped into | |
| 213 groups that have the same difference and conflict characteristics. When | |
| 214 clicking into the summary column with the left mouse button in either window | |
| 215 then the group belonging to that line will be selected in all windows and | |
| 216 the beginning of that group will be shown. (This might involve an automatic | |
| 217 position jump in the windows if the beginning of a group is not visible.) | |
| 218 <br> | |
| 219 Note the input selector buttons containing the letters "A", "B" and "C" | |
| 220 in the button bar below the menu bar. When clicking on either input selector | |
| 221 button, the lines from that input will be added at the end of the selected | |
| 222 group if that group didn't contain that source before. Otherwise the lines | |
| 223 from that input will be removed. </p> | |
| 224 | |
| 225 <p>Besides, you can directly edit any line. The summary column will show | |
| 226 "m" for every line that was modified . </p> | |
| 227 | |
| 228 <p>Sometimes, when a line is removed either by automatic merge or be editing | |
| 229 and no other lines remain in that group, then the text <No src line> | |
| 230 will appear in that line. This is just a placeholder for the group for when | |
| 231 you might change your mind and select some source again. This text won't appear | |
| 232 in the saved file or in any selections you want to copy and paste. </p> | |
| 233 | |
| 234 <p>The text "<Merge Conflict>" will not appear either if you copy and | |
| 235 paste some text containing that line. Be careful to do so! </p> | |
| 236 | |
| 237 <h3> Navigation And Editing</h3> | |
| 238 Much navigation will be done with the scroll bars and the mouse but you | |
| 239 can also navigate with the keys. If you click into either window then you | |
| 240 can use the cursor buttons left, right, up, down, page up, page down, home, | |
| 241 end, ctrl-home, ctrl-end as you would in other programs. The overview-column | |
| 242 next to the vertical scroll bar of the input files can also be used | |
| 243 for navigating by clicking into it. | |
| 244 <p>In the merge output editor you can also use the other keys for editing. | |
| 245 You can toggle between insert and overwrite mode with the insert key. (Default | |
| 246 is insert-mode.) </p> | |
| 247 | |
| 248 <p>A left-mouse-button-click into any summary column will synchronise all | |
| 249 windows to show the beginning of the same group of lines (as explained above, | |
| 250 see Merging). </p> | |
| 251 | |
| 252 <p>The button bar also contains six navigation buttons with which you can | |
| 253 jump to the first/last group of lines, to the next/previous difference group | |
| 254 or to the next/previous conflict. </p> | |
| 255 | |
| 256 <h3> Select, Copy And Paste</h3> | |
| 257 The input windows don't show a cursor, so selections must be made with | |
| 258 the mouse by clicking with the left mouse button at the start, holding down | |
| 259 the mousebutton and moving to the end, where you release the mouse button | |
| 260 again. You can also select a word by double clicking it. In the merge output | |
| 261 editor you can also select via the keyboard by holding the "shift"-button | |
| 262 and navigation with the cursor keys. | |
| 263 <p>To copy to the clipboard you must press the "Copy"-button or Ctrl-C. But | |
| 264 there exists an option "Auto Copy Selection". If this is enabled, then whatever | |
| 265 you select is copied immediately and you don't need to explicitely copy. But | |
| 266 pay attention when using this because the contents of the clipboard might | |
| 267 then be destroyed accidentally. </p> | |
| 268 | |
| 269 <p>"Cut" (Ctrl-X) copies to the clipboard and deletes the selected text and | |
| 270 "Paste" (Ctrl-V) inserts the text in the clipboard at the cursorposition | |
| 271 or over the current selection. </p> | |
| 272 | |
| 273 <h3> Options</h3> | |
| 274 Options and the recent-file-list will be saved when you exit the program, | |
| 275 and reloaded when you start it. | |
| 276 <h4> Font</h4> | |
| 277 Select a fixed width font. (On some systems this dialog will also present | |
| 278 variable width fonts, but you should not use them.) | |
| 279 <h4> Colors</h4> | |
| 280 Foreground color: Usually black. <br> | |
| 281 Background color: Usually white. <br> | |
| 282 Diff Background color: Usually light gray. <br> | |
| 283 Color A: Usually dark blue. <br> | |
| 284 Color B: Usually dark green. <br> | |
| 285 Color C: Usually dark magenta. <br> | |
| 286 Conflict Color: Usually red. | |
| 287 <h4> Editor Settings</h4> | |
| 288 Tab inserts spaces: If this is disabled and you press the tabulator key, | |
| 289 a tab-character is inserted, otherwise the appropriate amount of characters | |
| 290 is inserted. <br> | |
| 291 Tab size: Can be adjusted for your specific needs. Default is 8. <br> | |
| 292 Auto indentation: When pressing Enter or Return the indentation of the previous | |
| 293 line is used for the new line. <br> | |
| 294 Auto copy selection: Every selection is immediately copied to the clipboard | |
| 295 when active and you needn't explicitely copy it. | |
| 296 <h4> Diff Settings</h4> | |
| 297 Ignore white space: Default is on. White space will be ignored in the first | |
| 298 part of the analysis in which the line matching is done. In the result the | |
| 299 white space differences will be shown nevertheless. <br> | |
| 300 Ignore trivial matches: Default is on. When trivial lines match after an | |
| 301 difference, this will be ignored and the search for a nontrivial matching | |
| 302 line continues. This improves the results for inputs with empty lines and | |
| 303 lines containing only a open or close-brace character, which is often the | |
| 304 case for C/C++-programs. <br> | |
| 305 <br> | |
| 306 | |
| 307 <h2> <a name="faq"></a> | |
| 308 Questions And Answers</h2> | |
| 309 | |
| 310 <h4> Why is it called KDiff3?</h4> | |
| 311 Tools named KDiff and KDiff2 already exist. Also "KDiff3" should suggest | |
| 312 that it can merge like the "diff3"-tool in the Diff-Tool collection. | |
| 313 <h4> Why did I release it under GPL?</h4> | |
| 314 I'm using GPL programs for a very long time now and learned very much by | |
| 315 having a look at many of the sources. Hence this is my "Thank You" to all | |
| 316 programmers that also did so or will do the same. | |
| 317 <h4> Often lines that are similar but not identical appear next to each other | |
| 318 but sometimes not. Why?</h4> | |
| 319 Lines where only the amount of white space characters is different are | |
| 320 treated as "equal" at first, while just one different non-white character | |
| 321 causes the lines to be "different". If similar lines appear next to each | |
| 322 other, this actually is coincidence but this fortunately is often the case. | |
| 323 | |
| 324 <h4> Sometimes lines that are identical don't appear next to each other. Why?</h4> | |
| 325 Lines that contain very few (less than three) non-white characters are | |
| 326 not used for a match after a difference. Also solitary matching lines in | |
| 327 the middle of differences are not used for matching if they are too far apart. | |
| 328 Most of the time this behaviour improves the quality of the diff-analysis. | |
| 329 But if users (that includes you!) tell me that they need a different behaviour, | |
| 330 then I'll make this an option in the next version. | |
| 331 <h4> Why won't the merge tool automatically merge if both changes are equal?</h4> | |
| 332 Previously I also thought this would be nice, but when I tried it, I saw | |
| 333 that this is dangerous. Sometimes by coincindence two changes are identical | |
| 334 in certain lines but not otherwise. When this is merged automatically then | |
| 335 these lines that are actually needed twice - once for each change - only | |
| 336 appear once in the merge result. It can even happen that no other conflict | |
| 337 appears in the vicinity and then the problem goes completely unnoticed. | |
| 338 <h4> Why must all conflicts be solved before the merge result can be saved?</h4> | |
| 339 For each equal or different section the editor in the merge result window | |
| 340 remembers where it begins or ends. This is needed so that conflicts can | |
| 341 be solved manually by simply selecting the source button (A, B or C). This | |
| 342 information is lost while saving as text and it is too much effort to create | |
| 343 a special file format that supports saving and restoring all necessary information. | |
| 344 | |
| 345 <h4> Why does the editor in the merge result window not have an "undo"-function?</h4> | |
| 346 This was too much effort to do in the first version. And you can always | |
| 347 restore a version from one source (A, B or C) by clicking the respective | |
| 348 button. For big editing the use of another editor is recommended anyway. | |
| 349 | |
| 350 <h4> When I removed some text, then suddenly "<No src line>" appeared | |
| 351 and can't be deleted. What does that mean and how can one remove this?</h4> | |
| 352 For each equal or different section the editor in the merge result window | |
| 353 remembers where it begins or ends. "<No src line>" means that | |
| 354 there is nothing left in a section, not even a new line character. This | |
| 355 can happen either while merging automatically or by editing. This is no problem, | |
| 356 since this hint won't appear in the saved file. If you want the orignal source | |
| 357 back just select the section (click on the left summary column) and then click | |
| 358 the source button with the needed contents (A/B or C). | |
| 359 <h4> Why doesn't KDiff3 support syntax-highlighting?</h4> | |
| 360 KDiff3 already uses many colors for difference highlighting. More highlighting | |
| 361 would be confusing. Use another editor for this. <br> | |
| 362 | |
| 363 <h4>There is so much information here, but your question is still not answered?</h4> | |
| 364 Please send me your question. I appreciate every comment.<br> | |
| 365 | |
| 366 </body> | |
| 367 </html> |