<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 SYSTEM "../../../dtd/dblite.dtd">
<sect1 id="tsvn-dug-diff">
  <title>Viewing Differences</title>
  <indexterm>
    <primary>diff</primary>
  </indexterm>
  <indexterm>
    <primary>compare</primary>
  </indexterm>
  <para>
    One of the commonest requirements in project development is to
    see what has changed. You might want to look at the differences
    between two revisions of the same file, or the differences between
    two separate files.
    TortoiseSVN provides a built-in tool named
    <application>TortoiseMerge</application> for viewing differences of
    text files. For viewing differences of image files, TortoiseSVN
    also has a tool named <application>TortoiseIDiff</application>.
    Of course, you can use your own favourite diff program if you
    like.
  </para>
  <sect2 id="tsvn-dug-diff-file">
    <?dbhh topicname="HIDD_URLDIFF"?>
    <title>File Differences</title>
    <variablelist>
      <varlistentry>
        <term>Local changes</term>
        <listitem>
          <para>
            If you want to see what changes <emphasis>you</emphasis>
            have made in your working copy, just use the explorer
            context menu and select
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff</guimenuitem>
            </menuchoice>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference to another branch/tag</term>
        <listitem>
          <para>
            If you want to see what has changed on trunk (if you are
            working on a branch) or on a specific branch (if you are
            working on trunk), you can use the explorer context menu.
            Just hold down the <keycap>Shift</keycap> key while you
            right click on the file. Then select
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff with URL</guimenuitem>
            </menuchoice>. In the following dialog, specify the URL in
            the repository with which you want to compare your local
            file to.
          </para>
          <para>
            You can also use the repository browser and select two
            trees to diff, perhaps two tags, or a branch/tag and trunk.
            The context menu there allows you to compare them
            using <guimenuitem>Compare revisions</guimenuitem>.
            Read more in <xref linkend="tsvn-dug-compare-revs"/>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference from a previous revision</term>
        <listitem>
          <para>
            If you want to see the difference between a particular
            revision and your working copy, use the Revision Log
            dialog, select the revision of interest, then select
            <guimenuitem>Compare with working copy</guimenuitem>
            from the context menu.
          </para>
          <para>
            If you want to see the difference between the last committed
            revision and your working copy, assuming that the working copy
            hasn't been modified, just right click on the file. Then select
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff with previous version</guimenuitem>
            </menuchoice>.
            This will perform a diff between the revision before
            the last-commit-date (as recorded in your working copy) and the
            working BASE. This shows you the last change made to that file
            to bring it to the state you now see in your working copy.
            It will not show changes newer than your working copy.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference between two previous revisions</term>
        <listitem>
          <para>
            If you want to see the difference between two revisions
            which are already committed, use the Revision Log
            dialog and select the two revisions you want to compare
            (using the usual <keycap>Ctrl</keycap>-modifier).
            Then select <guimenuitem>Compare revisions</guimenuitem>
            from the context menu.
          </para>
          <para>
            If you did this from the revision log for a folder,
            a Compare Revisions dialog appears, showing a list
            of changed files in that folder. Read more in
            <xref linkend="tsvn-dug-compare-revs"/>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>All changes made in a commit</term>
        <listitem>
          <para>
            If you want to see the changes made to all files
            in a particular revision in one view, you can
            use Unified-Diff output (GNU patch format). This shows
            only the differences with a few lines of context. It
            is harder to read than a visual file compare, but will
            show all the changes together. From the Revision Log
            dialog select the revision of interest, then select
            <guimenuitem>Show Differences as Unified-Diff</guimenuitem>
            from the context menu.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference between files</term>
        <listitem>
          <para>
            If you want to see the differences between two different
            files, you can do that directly in explorer by selecting
            both files (using the usual <keycap>Ctrl</keycap>-modifier).
            Then from the explorer context menu select
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff</guimenuitem>
            </menuchoice>.
          </para>
          <para>
            If the files to compare are not located in the same folder,
            use the command
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff later</guimenuitem>
            </menuchoice>
            to mark the first file for diffing, then browse to the second
            file and use
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff with &quot;path/of/marked/file&quot;</guimenuitem>
            </menuchoice>.
            To remove the marked file, use the command
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff later</guimenuitem>
            </menuchoice> again, but hold down the <keycap>Ctrl</keycap>-modifier
            while clicking on it.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference between WC file/folder and a URL</term>
        <listitem>
          <para>
            If you want to see the differences between a file in your
            working copy, and a file in any Subversion repository,
            you can do that directly in explorer by selecting the
            file then holding down the <keycap>Shift</keycap> key whilst
            right clicking to obtain the context menu. Select
            <menuchoice>
              <guimenu>TortoiseSVN</guimenu>
              <guimenuitem>Diff with URL</guimenuitem>
            </menuchoice>.
            You can do the same thing for a working copy folder.
            TortoiseMerge shows these differences in the same way
            as it shows a patch file - a list of changed files which
            you can view one at a time.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference with blame information</term>
        <listitem>
          <para>
            If you want to see not only the differences but also the author,
            revision and date that changes were made, you can combine the
            diff and blame reports from within the revision log dialog.
            Read <xref linkend="tsvn-dug-blame-diffs"/> for more detail.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Difference between folders</term>
        <listitem>
          <para>
            The built-in tools supplied with TortoiseSVN do not support
            viewing differences between directory hierarchies. But if you
            have an external tool which does support that feature, you can
            use that instead. In <xref linkend="tsvn-dug-diff-tools"/>
            we tell you about some tools which we have used.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
      If you have configured a third party diff tool, you can use
      <keycap>Shift</keycap> when selecting the Diff command to
      use the alternate tool.
      Read <xref linkend="tsvn-dug-settings-progs"/> to
      find out about configuring other diff tools.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-diff-eol-whitespace">
    <title>Line-end and Whitespace Options</title>
    <para>
      Sometimes in the life of a project you might change the line endings
      from <literal>CRLF</literal> to <literal>LF</literal>, or you may
      change the indentation of a section. Unfortunately this will mark
      a large number of lines as changed, even though there is no change
      to the meaning of the code. The options here will help to manage
      these changes when it comes to comparing and applying differences.
      You will see these settings in the <guilabel>Merge</guilabel> and
      <guilabel>Blame</guilabel> dialogs, as well as in the settings for
      TortoiseMerge.
    </para>
    <para>
      <guilabel>Ignore line endings</guilabel>
      excludes changes which are due solely to difference in line-end style.
    </para>
    <para>
      <guilabel>Compare whitespaces</guilabel>
      includes all changes in indentation and inline whitespace as
      added/removed lines.
    </para>
    <para>
      <guilabel>Ignore whitespace changes</guilabel>
      excludes changes which are due solely to a change in the
      amount or type of whitespace, e.g. changing the indentation
      or changing tabs to spaces. Adding whitespace where there
      was none before, or removing a whitespace completely is still
      shown as a change.
    </para>
    <para>
      <guilabel>Ignore all whitespaces</guilabel>
      excludes all whitespace-only changes.
    </para>
    <para>
      Naturally, any line with changed content is always included in
      the diff.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-compare-revs">
    <title>Comparing Folders</title>
    <?dbhh topicname="HIDD_DIFFFILES"?>
    <indexterm>
      <primary>compare revisions</primary>
    </indexterm>
    <indexterm>
      <primary>export changes</primary>
    </indexterm>
    <para>
      <figure id="tsvn-dug-compare-revs-dia-1">
        <title>The Compare Revisions Dialog</title>
        <graphic fileref="../images/CompareRevisions.png"/>
      </figure>
      When you select two trees within the repository browser, or when
      you select two revisions of a folder in the log dialog, you can
      <menuchoice>
        <guimenu>Context menu</guimenu>
        <guimenuitem>Compare revisions</guimenuitem>
      </menuchoice>.
    </para>
    <para>
      This dialog shows a list of all files which have changed and allows
      you to compare or blame them individually using context menu.
    </para>
    <para>
      You can export a <emphasis>change tree</emphasis>, which is useful
      if you need to send someone else your project tree structure, but
      containing only the files which have changed.
      This operation works on the selected files only, so you need
      to select the files of interest - usually that means all of them -
      and then
      <menuchoice>
        <guimenu>Context menu</guimenu>
        <guimenuitem>Export selection to...</guimenuitem>
      </menuchoice>.
      You will be prompted for a location to save the change tree.
    </para>
    <para>
      You can also export the <emphasis>list</emphasis> of changed files
      to a text file using
      <menuchoice>
        <guimenu>Context menu</guimenu>
        <guimenuitem>Save list of selected files to...</guimenuitem>
      </menuchoice>.
    </para>
    <para>
      If you want to export the list of files <emphasis>and</emphasis>
      the actions (modified, added, deleted) as well, you can do that using
      <menuchoice>
        <guimenu>Context menu</guimenu>
        <guimenuitem>Copy selection to clipboard</guimenuitem>
      </menuchoice>.
    </para>
    <para>
      The button at the top allows you to change the direction of
      comparison. You can show the changes need to get from A to B,
      or if you prefer, from B to A.
    </para>
    <para>
      The buttons with the revision numbers on can be used to change to a
      different revision range. When you change the range, the list of items
      which differ between the two revisions will be updated automatically.
    </para>
    <para>
      If the list of filenames is very long, you can use the search box
      to reduce the list to filenames containing specific text. Note that
      a simple text search is used, so if you want to restrict the list
      to C source files you should enter <filename>.c</filename> rather than
      <filename>*.c</filename>.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-idiff">
    <title>Diffing Images Using TortoiseIDiff</title>
    <indexterm>
      <primary>image diff</primary>
    </indexterm>
    <indexterm>
      <primary>TortoiseIDiff</primary>
    </indexterm>
    <para>
      There are many tools available for diffing text files, including our
      own TortoiseMerge, but we often find ourselves wanting to see how
      an image file has changed too. That's why we created TortoiseIDiff.
    </para>
    <para>
      <figure id="tsvn-dug-idiff-dia-1">
        <title>The image difference viewer</title>
        <graphic fileref="../images/TortoiseIDiff.png"/>
      </figure>
      <menuchoice>
        <guimenu>TortoiseSVN</guimenu>
        <guimenuitem>Diff</guimenuitem>
      </menuchoice>
      for any of the common image file formats will start TortoiseIDiff
      to show image differences. By default the images are displayed side-by-side
      but you can use the View menu or toolbar to switch to a top-bottom
      view instead, or if you prefer, you can overlay the images and pretend
      you are using a lightbox.
    </para>
    <para>
      Naturally you can also zoom in and out and pan around the image.
      You can also pan the image simply by left-dragging it.
      If you select the <guilabel>Link images together</guilabel> option,
      then the pan controls (scrollbars, mousewheel) on both images are linked.
    </para>
    <para>
      An image info box shows details about the image file, such as the
      size in pixels, resolution and colour depth. If this box gets in the
      way, use
      <menuchoice>
        <guimenu>View</guimenu>
        <guimenuitem>Image Info</guimenuitem>
      </menuchoice>
      to hide it.
      You can get the same information in a tooltip if you hover the mouse
      over the image title bar.
    </para>
    <para>
      When the images are overlaid, the relative intensity of the images
      (alpha blend) is controlled by a slider control at the left side.
      You can click anywhere in the slider to set the blend directly, or you
      can drag the slider to change the blend interactively.
      <keycap>Ctrl+Shift</keycap>-<action>Wheel</action> to change the blend.
    </para>
    <para>
      The button above the slider toggles between 0% and 100% blends, and
      if you double click the button, the blend toggles automatically every
      second until you click the button again. This can be useful when looking
      for multiple small changes.
    </para>
    <para>
      Sometimes you want to see a difference rather than a blend. You might
      have the image files for two revisions of a printed circuit board and
      want to see which tracks have changed. If you disable alpha blend mode,
      the difference will be shown as an <emphasis>XOR</emphasis> of the pixel
      colour values. Unchanged areas will be plain white and changes will be
      coloured.
    </para>
  </sect2>
  <sect2 id="tsvn-dug-diff-custom">
    <title>Diffing Office Documents</title>
    <indexterm>
      <primary>Microsoft Word</primary>
    </indexterm>
    <para>
      When you want to diff non-text documents you normally have to use the
      software used to create the document as it understands the file format.
      For the commonly used Microsoft Office and Open Office suites there
      is indeed some support for viewing differences and TortoiseSVN
      includes scripts to invoke these with the right settings when you
      diff files with the well-known file extensions. You can check which
      file extensions are supported and add your own by going to
      <menuchoice>
        <guimenu>TortoiseSVN</guimenu>
        <guimenuitem>Settings</guimenuitem>
      </menuchoice>
      and clicking <guibutton>Advanced</guibutton> in the
      <guilabel>External Programs</guilabel> section.
    </para>
    <tip>
      <title>Problems with Office 2010</title>
      <para>
        If you installed the <emphasis>Click-to-Run</emphasis> version of
        Office 2010 and you try to diff documents you may get an error message
        from Windows Script Host something like this:
        <quote>ActiveX component can't create object: word.Application</quote>.
        It seems you have to use the MSI-based version of Office to get
        the diff functionality.
      </para>
    </tip>
  </sect2>
  <sect2 id="tsvn-dug-diff-tools">
    <title>External Diff/Merge Tools</title>
    <indexterm>
      <primary>diff tools</primary>
    </indexterm>
    <indexterm>
      <primary>merge tools</primary>
    </indexterm>
    <para>
      If the tools we provide don't do what you need, try one of the many
      open-source or commercial programs available. Everyone has their own
      favourites, and this list is by no means complete, but here are a few
      that you might consider:
    </para>
    <variablelist>
      <varlistentry>
        <term>WinMerge</term>
        <listitem>
          <para>
            <ulink url="https://winmerge.org/">
              <citetitle>WinMerge</citetitle>
            </ulink>
            is a great open-source diff tool which can also
            handle directories.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Perforce Merge</term>
        <listitem>
          <para>
            Perforce is a commercial RCS, but you can download the
            diff/merge tool for free. Get more information from
            <ulink url="https://www.perforce.com/perforce/products/merge.html">
              <citetitle>Perforce</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>KDiff3</term>
        <listitem>
          <para>
            KDiff3 is a free diff tool which can also handle
            directories. You can download it from
            <ulink url="https://download.kde.org/stable/kdiff3/">
              <citetitle>here</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>SourceGear DiffMerge</term>
        <listitem>
          <para>
            SourceGear Vault is a commercial RCS, but you can download the
            diff/merge tool for free. Get more information from
            <ulink url="https://www.sourcegear.com/diffmerge/">
              <citetitle>SourceGear</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>ExamDiff</term>
        <listitem>
          <para>
            ExamDiff Standard is freeware. It can handle
            files but not directories.
            ExamDiff Pro is shareware and adds a number
            of goodies including directory diff and editing
            capability.
            In both flavours, version 3.2 and above can handle
            unicode. You can download them from
            <ulink url="https://www.prestosoft.com/">
              <citetitle>PrestoSoft</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Beyond Compare</term>
        <listitem>
          <para>
            Similar to ExamDiff Pro, this is an excellent shareware
            diff tool which can handle directory diffs and unicode.
            Download it from
            <ulink url="https://www.scootersoftware.com/">
              <citetitle>Scooter Software</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Araxis Merge</term>
        <listitem>
          <para>
            Araxis Merge is a useful commercial tool for diff and merging
            both files and folders. It does three-way comparison in merges
            and has synchronization links to use if you've changed the order
            of functions. Download it from
            <ulink url="https://www.araxis.com/merge/index.html">
              <citetitle>Araxis</citetitle>
            </ulink>.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>
      Read <xref linkend="tsvn-dug-settings-progs"/> for information
      on how to set up TortoiseSVN to use these tools.
    </para>
  </sect2>
</sect1>
