1 <?xml version="1.0" encoding="UTF-8"?>
\r
2 <!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
\r
3 <sect1 id="tsvn-dug-diff">
\r
4 <title>Viewing Differences</title>
\r
6 <primary>diff</primary>
\r
9 <primary>compare</primary>
\r
12 One of the commonest requirements in project development is to
\r
13 see what has changed. You might want to look at the differences
\r
14 between two revisions of the same file, or the differences between
\r
16 TortoiseGit provides a built-in tool named
\r
17 <application>TortoiseMerge</application> for viewing differences of
\r
18 text files. For viewing differences of image files, TortoiseGit
\r
19 also has a tool named <application>TortoiseIDiff</application>.
\r
20 Of course, you can use your own favourite diff program if you
\r
23 <sect2 id="tsvn-dug-diff-file">
\r
24 <?dbhh topicname="HIDD_URLDIFF"?>
\r
25 <title>File Differences</title>
\r
28 <term>Local changes</term>
\r
31 If you want to see what changes <emphasis>you</emphasis>
\r
32 have made in your working tree, just use the explorer
\r
33 context menu and select
\r
35 <guimenu>TortoiseGit</guimenu>
\r
36 <guimenuitem>Diff</guimenuitem>
\r
43 <term>Difference to another branch/tag</term>
\r
46 If you want to see what has changed on trunk (if you are
\r
47 working on a branch) or on a specific branch (if you are
\r
48 working on trunk), you can use the explorer context menu.
\r
49 Just hold down the <keycap>Shift</keycap> key while you
\r
50 right click on the file. Then select
\r
52 <guimenu>TortoiseGit</guimenu>
\r
53 <guimenuitem>Diff with URL</guimenuitem>
\r
54 </menuchoice>. In the following dialog, specify the URL in
\r
55 the repository with which you want to compare your local
\r
59 You can also use the repository browser and select two
\r
60 trees to diff, perhaps two tags, or a branch/tag and trunk.
\r
61 The context menu there allows you to compare them
\r
62 using <guimenuitem>Compare revisions</guimenuitem>.
\r
63 Read more in <xref linkend="tsvn-dug-compare-revs"/>.
\r
69 <term>Difference from a previous revision</term>
\r
72 If you want to see the difference between a particular
\r
73 revision and your working tree, use the Revision Log
\r
74 dialog, select the revision of interest, then select
\r
75 <guimenuitem>Compare with working tree</guimenuitem>
\r
76 from the context menu.
\r
79 If you want to see the difference between the last committed
\r
80 revision and your working tree, assuming that the working tree
\r
81 hasn't been modified, just right click on the file. Then select
\r
83 <guimenu>TortoiseGit</guimenu>
\r
84 <guimenuitem>Diff with previous version</guimenuitem>
\r
86 This will perform a diff between the revision before
\r
87 the last-commit-date (as recorded in your working tree) and the
\r
88 working BASE. This shows you the last change made to that file
\r
89 to bring it to the state you now see in your working tree.
\r
90 It will not show changes newer than your working tree.
\r
95 <term>Difference between two previous revisions</term>
\r
98 If you want to see the difference between two revisions
\r
99 which are already committed, use the Revision Log
\r
100 dialog and select the two revisions you want to compare
\r
101 (using the usual <keycap>Ctrl</keycap>-modifier).
\r
102 Then select <guimenuitem>Compare revisions</guimenuitem>
\r
103 from the context menu.
\r
106 If you did this from the revision log for a folder,
\r
107 a Compare Revisions dialog appears, showing a list
\r
108 of changed files in that folder. Read more in
\r
109 <xref linkend="tsvn-dug-compare-revs"/>.
\r
114 <term>All changes made in a commit</term>
\r
117 If you want to see the changes made to all files
\r
118 in a particular revision in one view, you can
\r
119 use Unified-Diff output (GNU patch format). This shows
\r
120 only the differences with a few lines of context. It
\r
121 is harder to read than a visual file compare, but will
\r
122 show all the changes together. From the Revision Log
\r
123 dialog select the revision of interest, then select
\r
124 <guimenuitem>Show Differences as Unified-Diff</guimenuitem>
\r
125 from the context menu.
\r
130 <term>Difference between files</term>
\r
133 If you want to see the differences between two different
\r
134 files, you can do that directly in explorer by selecting
\r
135 both files (using the usual <keycap>Ctrl</keycap>-modifier).
\r
136 Then from the explorer context menu select
\r
138 <guimenu>TortoiseGit</guimenu>
\r
139 <guimenuitem>Diff</guimenuitem>
\r
146 <term>Difference between working tree file/folder and a URL</term>
\r
149 If you want to see the differences between a file in your
\r
150 working tree, and a file in any Git repository,
\r
151 you can do that directly in explorer by selecting the
\r
152 file then holding down the <keycap>Shift</keycap> key whilst
\r
153 right clicking to obtain the context menu. Select
\r
155 <guimenu>TortoiseGit</guimenu>
\r
156 <guimenuitem>Diff with URL</guimenuitem>
\r
158 You can do the same thing for a working tree folder.
\r
159 TortoiseMerge shows these differences in the same way
\r
160 as it shows a patch file - a list of changed files which
\r
161 you can view one at a time.
\r
168 <term>Difference with blame information</term>
\r
171 If you want to see not only the differences but also the author,
\r
172 revision and date that changes were made, you can combine the
\r
173 diff and blame reports from within the revision log dialog.
\r
174 Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.
\r
180 <term>Difference between folders</term>
\r
183 The built-in tools supplied with TortoiseGit do not support
\r
184 viewing differences between directory hierarchies. But if you
\r
185 have an external tool which does support that feature, you can
\r
186 use that instead. In <xref linkend="tsvn-dug-diff-tools"/>
\r
187 we tell you about some tools which we have used.
\r
193 If you have configured a third party diff tool, you can use
\r
194 <keycap>Shift</keycap> when selecting the Diff command to
\r
195 use the alternate tool.
\r
196 Read <xref linkend="tsvn-dug-settings-progs"/> to
\r
197 find out about configuring other diff tools.
\r
200 <sect2 id="tsvn-dug-diff-eol-whitespace">
\r
201 <title>Line-end and Whitespace Options</title>
\r
203 Sometimes in the life of a project you might change the line endings
\r
204 from <literal>CRLF</literal> to <literal>LF</literal>, or you may
\r
205 change the indentation of a section. Unfortunately this will mark
\r
206 a large number of lines as changed, even though there is no change
\r
207 to the meaning of the code. The options here will help to manage
\r
208 these changes when it comes to comparing and applying differences.
\r
209 You will see these settings in the <guilabel>Merge</guilabel> and
\r
210 <guilabel>Blame</guilabel> dialogs, as well as in the settings for
\r
214 <guilabel>Ignore line endings</guilabel>
\r
215 excludes changes which are due solely to difference in line-end style.
\r
218 <guilabel>Compare whitespaces</guilabel>
\r
219 includes all changes in indentation and inline whitespace as
\r
220 added/removed lines.
\r
223 <guilabel>Ignore whitespace changes</guilabel>
\r
224 excludes changes which are due solely to a change in the
\r
225 amount or type of whitespace, eg. changing the indentation
\r
226 or changing tabs to spaces. Adding whitespace where there
\r
227 was none before, or removing a whitespace completely is still
\r
231 <guilabel>Ignore all whitespaces</guilabel>
\r
232 excludes all whitespace-only changes.
\r
235 Naturally, any line with changed content is always included in
\r
239 <sect2 id="tsvn-dug-compare-revs">
\r
240 <title>Comparing Version</title>
\r
242 <primary>compare revisions</primary>
\r
245 <primary>export changes</primary>
\r
247 <?dbhh topicname="HIDD_DIFFFILES"?>
\r
249 <figure id="tsvn-dug-compare-revs-dia-1">
\r
250 <title>The Compare Revisions Dialog</title>
\r
251 <graphic fileref="../images/CompareRevisions.png"/>
\r
253 In log dialog, when you select two commits
\r
255 <guimenu>Context menu</guimenu>
\r
256 <guimenuitem>Compare revisions</guimenuitem>
\r
258 , or when you select a commit
\r
260 <guimenu>Context menu</guimenu>
\r
261 <guimenuitem>Compare with previous version / Compare with working tree</guimenuitem>
\r
263 ; or in Windows Explorer, when you select no files
\r
265 <guimenu>TortoiseGit context menu</guimenu>
\r
266 <guimenuitem>Diff with previous version</guimenuitem>
\r
268 , Compare Revisions Dialog shows.
\r
271 This dialog shows a list of all files which have changed and allows
\r
272 you to compare them individually using context menu.
\r
275 You can Revert selected files to version 1 or version 2.
\r
276 There are 2 menu items for this purpose.
\r
278 <guimenu>Context menu</guimenu>
\r
279 <guimenuitem>Revert to revision xxxxxxx / Revert to revision yyyyyyy</guimenuitem>
\r
281 where xxxxxxx is revision 1 short hash and yyyyyyy revision is 2 short hash.
\r
284 You can export a <emphasis>change tree</emphasis>, which is useful
\r
285 if you need to send someone else your project tree structure, but
\r
286 containing only the files which have changed.
\r
287 This operation works on the selected files only, so you need
\r
288 to select the files of interest - usually that means all of them -
\r
291 <guimenu>Context menu</guimenu>
\r
292 <guimenuitem>Export selection to...</guimenuitem>
\r
294 You will be prompted for a location to save the change tree.
\r
297 You can also export the <emphasis>list</emphasis> of changed files
\r
298 to a text file using
\r
300 <guimenu>Context menu</guimenu>
\r
301 <guimenuitem>Save list of selected files to...</guimenuitem>
\r
305 If you want to export the list of files <emphasis>and</emphasis>
\r
306 the actions (modified, added, deleted) as well, you can do that using
\r
308 <guimenu>Context menu</guimenu>
\r
309 <guimenuitem>Copy selection to clipboard</guimenuitem>
\r
313 The button at the top allows you to change the direction of
\r
314 comparison. You can show the changes need to get from A to B,
\r
315 or if you prefer, from B to A.
\r
318 The buttons with the revision numbers on can be used to change to a
\r
319 different revision range. When you change the range, the list of items
\r
320 which differ between the two revisions will be updated automatically.
\r
323 If the list of filenames is very long, you can use the search box
\r
324 to reduce the list to filenames containing specific text. Note that
\r
325 a simple text search is used, so if you want to restrict the list
\r
326 to C source files you should enter <filename>.c</filename> rather than
\r
327 <filename>*.c</filename>.
\r
330 <sect2 id="tsvn-dug-submodulediff">
\r
331 <title>Diffing submodules using Submodule Diff Dialog</title>
\r
333 <primary>Submodule Diff Dialog</primary>
\r
336 The built-in diff command of git is available for diffing submodules,
\r
337 but we often find ourselves wanting to see more details how
\r
338 a submodule has changed too. That's why we created Submodule Diff Dialog.
\r
341 <figure id="tsvn-dug-submodulediff-dia-1">
\r
342 <title>The submodule difference dialog</title>
\r
343 <graphic fileref="../images/SubmoduleDiff.png"/>
\r
346 <guimenu>TortoiseGit</guimenu>
\r
347 <guimenuitem>Diff</guimenuitem>
\r
349 for submodules will start Submodule Diff Dialog to show submodules differences.
\r
350 The summary of the two revisions are displayed.
\r
353 The 'From' group box on the top displays the information of the original revision.
\r
354 Below it, there is a 'To' group box, which display the information of the changed revision.
\r
355 For each group box, the full commit hash is displayed, and can be highlighted and copied to clipboard;
\r
356 the subject (i.e. first line of commit message) is displayed and also copiable to clipboard;
\r
357 the Show Log button brings you to a new Log Dialog and jump to that revision.
\r
360 To better draw the attention of the change of revision of submodule mounted,
\r
361 we added some indicators.
\r
362 In 'To' group box, there is a change type field. Here list out the types:
\r
365 <term>Fast-forward</term>
\r
368 Topology-based. This is for a fast-forward change.
\r
373 <term>Rewind</term>
\r
376 Topology-based. This is the reversed direction of a fast-forward change.
\r
381 <term>Newer commit time</term>
\r
384 Time-based. If it is neither fast-forward nor rewind, then we compare commit time.
\r
385 This is for a revision with newer commit time than the original revision.
\r
390 <term>Older commit time</term>
\r
393 Time-based. This is the reversal of 'Newer commit time'.
\r
398 <term>Same commit time</term>
\r
401 Time-based. The commit time is the same.
\r
402 This may be produced by auto-generating commits or committing at the same time by two persons.
\r
407 <term>New Submodule</term>
\r
410 This is for newly added submodule.
\r
415 <term>Delete Submodule</term>
\r
418 This is for deleted submodule.
\r
423 <term>Unknown</term>
\r
426 This is for submodule revision hash not changed, error, etc..
\r
432 If current workspace of the submodule is dirty,
\r
433 the commit hash will be rendered in yellow background and red text.
\r
436 In both group boxes,
\r
437 if the revision is not fetched, submodule not initialized or other errors,
\r
438 the commit hash will be rendered in red background.
\r
441 <sect2 id="tsvn-dug-idiff">
\r
442 <title>Diffing Images Using TortoiseIDiff</title>
\r
444 <primary>image diff</primary>
\r
447 <primary>TortoiseIDiff</primary>
\r
450 There are many tools available for diffing text files, including our
\r
451 own TortoiseMerge, but we often find ourselves wanting to see how
\r
452 an image file has changed too. That's why we created TortoiseIDiff.
\r
455 <figure id="tsvn-dug-idiff-dia-1">
\r
456 <title>The image difference viewer</title>
\r
457 <graphic fileref="../images/TortoiseIDiff.png"/>
\r
460 <guimenu>TortoiseGit</guimenu>
\r
461 <guimenuitem>Diff</guimenuitem>
\r
463 for any of the common image file formats will start TortoiseIDiff
\r
464 to show image differences. By default the images are displayed side-by-side
\r
465 but you can use the View menu or toolbar to switch to a top-bottom
\r
466 view instead, or if you prefer, you can overlay the images and pretend
\r
467 you are using a lightbox.
\r
470 Naturally you can also zoom in and out and pan around the image.
\r
471 You can also pan the image simply by left-dragging it.
\r
472 If you select the <guilabel>Link images together</guilabel> option,
\r
473 then the pan controls (scrollbars, mousewheel) on both images are linked.
\r
476 An image info box shows details about the image file, such as the
\r
477 size in pixels, resolution and colour depth. If this box gets in the
\r
480 <guimenu>View</guimenu>
\r
481 <guimenuitem>Image Info</guimenuitem>
\r
484 You can get the same information in a tooltip if you hover the mouse
\r
485 over the image title bar.
\r
488 When the images are overlaid, the relative intensity of the images
\r
489 (alpha blend) is controlled by a slider control at the left side.
\r
490 You can click anywhere in the slider to set the blend directly, or you
\r
491 can drag the slider to change the blend interactively.
\r
492 <keycap>Ctrl+Shift</keycap>-<action>Wheel</action> to change the blend.
\r
495 The button above the slider toggles between two preset blends, indicated
\r
496 by the markers on either side of the blend slider. By default one is at
\r
497 the top and the other at the bottom, so the toggle button just switches
\r
498 between one image and the other. You can move the markers to choose
\r
499 the two blend values that the toggle button will use.
\r
502 Sometimes you want to see a difference rather than a blend. You might
\r
503 have the image files for two revisions of a printed circuit board and
\r
504 want to see which tracks have changed. If you disable alpha blend mode,
\r
505 the difference will be shown as an <emphasis>XOR</emphasis> of the pixel
\r
506 colour values. Unchanged areas will be plain white and changes will be
\r
510 <sect2 id="tsvn-dug-diff-tools">
\r
511 <title>External Diff/Merge Tools</title>
\r
513 <primary>diff tools</primary>
\r
516 <primary>merge tools</primary>
\r
519 If the tools we provide don't do what you need, try one of the many
\r
520 open-source or commercial programs available. Everyone has their own
\r
521 favourites, and this list is by no means complete, but here are a few
\r
522 that you might consider:
\r
526 <term>WinMerge</term>
\r
529 <ulink url="http://winmerge.sourceforge.net/">
\r
530 <citetitle>WinMerge</citetitle>
\r
532 is a great open-source diff tool which can also
\r
533 handle directories.
\r
538 <term>Perforce Merge</term>
\r
541 Perforce is a commercial RCS, but you can download the
\r
542 diff/merge tool for free. Get more information from
\r
543 <ulink url="http://www.perforce.com/perforce/products/merge.html">
\r
544 <citetitle>Perforce</citetitle>
\r
550 <term>KDiff3</term>
\r
553 KDiff3 is a free diff tool which can also handle
\r
554 directories. You can download it from
\r
555 <ulink url="http://kdiff3.sf.net/">
\r
556 <citetitle>here</citetitle>
\r
562 <term>ExamDiff</term>
\r
565 ExamDiff Standard is freeware. It can handle
\r
566 files but not directories.
\r
567 ExamDiff Pro is shareware and adds a number
\r
568 of goodies including directory diff and editing
\r
570 In both flavours, version 3.2 and above can handle
\r
571 unicode. You can download them from
\r
572 <ulink url="http://www.prestosoft.com/">
\r
573 <citetitle>PrestoSoft</citetitle>
\r
579 <term>Beyond Compare</term>
\r
582 Similar to ExamDiff Pro, this is an excellent shareware
\r
583 diff tool which can handle directory diffs and unicode.
\r
585 <ulink url="http://www.scootersoftware.com/">
\r
586 <citetitle>Scooter Software</citetitle>
\r
592 <term>Araxis Merge</term>
\r
595 Araxis Merge is a useful commercial tool for diff and merging
\r
596 both files and folders. It does three-way comparison in merges
\r
597 and has synchronization links to use if you've changed the order
\r
598 of functions. Download it from
\r
599 <ulink url="http://www.araxis.com/merge/index.html">
\r
600 <citetitle>Araxis</citetitle>
\r
609 This text editor includes syntax colouring for unified diffs,
\r
610 making them much easier to read. Download it from
\r
611 <ulink url="http://www.scintilla.org/SciTEDownload.html">
\r
612 <citetitle>Scintilla</citetitle>
\r
618 <term>Notepad2</term>
\r
621 Notepad2 is designed as a replacement for the standard
\r
622 Windows Notepad program, and is based on the Scintilla
\r
623 open-source edit control. As well as being good for
\r
624 viewing unified diffs, it is much better than the
\r
625 Windows notepad for most jobs. Download it for free
\r
626 <ulink url="http://www.flos-freeware.ch/notepad2.html">
\r
627 <citetitle>here</citetitle>
\r
631 Notepad2 have been included at TortoiseGit Setup MSI.
\r
632 You can launch it by command line "notepad2".
\r
638 Read <xref linkend="tsvn-dug-settings-progs"/> for information
\r
639 on how to set up TortoiseGit to use these tools.
\r