<tip>
<para>Similarly, many GUI tools (like version control clients and IDEs)
that include built-in diff tools enable you to configure WinMerge as their
- default diff tool, instead. Examples include TortoiseSVN, Eclipse, and
- Perforce. Check their documentation or search the Internet for details and
- examples.</para>
+ default diff tool, instead. The next section describes how to use WinMerge
+ this way with TortoiseSVN, TortoiseCVS, and ClearCase. For other tools,
+ like Eclipse and Perforce, check their documentation or search the
+ Internet for details and examples.</para>
</tip>
</section>
- <section>
- <title>Integration with version control tools<indexterm>
+ <section id="VersionControl_vcs">
+ <title>Using WinMerge with version control systems<indexterm>
<primary>version control systems</primary>
<secondary>integration with</secondary>
</indexterm></title>
- <para>WinMerge can integrate some key functions with a few, specific version
- control system (VCS) tools. There are two methods for configuring optional
- VCS integrations: either during WinMerge installation or after
- installation:</para>
+ <para>You can configure WinMerge to interact with a few supported version
+ control systems (VCS) in two ways. This section describes the two types of
+ VCS integration and provides an example of each.</para>
- <itemizedlist>
- <listitem>
- <para>If the WinMerge installer detects that TortoiseSVN, TortoiseCVS,
- or Rational ClearCase is present on your system, the Setup Additional
- Tasks page contains options to enable its WinMerge integration. The
- installer does not detect Visual SourceSafe.</para>
- </listitem>
+ <section>
+ <title>Checking out versioned files from WinMerge</title>
- <listitem>
- <para>After installation, you can open the Options dialog and configure
- either the ClearCase or Visual SourceSafe integration, as described in
- <xref linkend="Configuration_vcs" />.</para>
- </listitem>
- </itemizedlist>
+ <indexterm>
+ <primary>Visual SourceSafe integration</primary>
+ </indexterm>
+
+ <para>When you save a file in WinMerge and the file is a versioned
+ ClearCase or Visual Source Safe element, WinMerge can open the VCS's
+ checkout dialog for you. This makes it easy to check out files as you are
+ working in WinMerge. However, WinMerge does not provide checkin or history
+ tools, so remember to check the files in later using the VCS
+ interface.</para>
- <para>Each WinMerge version control integration has one of these basic types
- of interaction:</para>
-
- <variablelist>
- <varlistentry>
- <term>WinMerge launches VCS file checkout</term>
-
- <listitem>
- <para>With version control systems that lock files (for example,
- ClearCase and Visual Source Safe), WinMerge opens the VCS's checkout
- dialog before saving a file. It is up to you to check out the file,
- and then to check in the file later using the VCS tools. WinMerge does
- not provide checkin or history tools.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>VCS use WinMerge as its diff tool</term>
-
- <listitem>
- <para>When you start a diff operation using TortoiseSVN and
- TortoiseCVS, the integration opens WinMerge instead of the VCS
- client's own diff utility.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <note>
- <para>If you enable the ClearCase integration</para>
- </note>
-
- <section id="VersionControl_cc">
- <title>About the ClearCase integration</title>
-
- <para>If you use choose the option to integrate with Rational ClearCase
- during WinMerge installation, the installer:</para>
-
- <orderedlist>
- <listitem>
- <para>Creates a backup copy of the ClearCase <filename>map</filename>
- file, <filename>map.bak</filename>, in the
- <filename><replaceable>ccase-home-dir</replaceable>\lib\mgrs</filename>
- directory. The <filename>map</filename> file is a user-configurable
- file that associates ClearCase methods with the programs that carry
- them out.</para>
- </listitem>
-
- <listitem>
- <para>In the the <filename>map</filename> file, modifies the
- <guilabel>text_file_delta</guilabel> field to specify WinMerge instead
- of the default <filename>cleardiff.exe</filename> when running the
- <command>cleartool diff</command> command.</para>
- </listitem>
- </orderedlist>
-
- <para>If you later want to disable the ClearCase integration, click
- <menuchoice>
+ <para>This integration is available after WinMerge installation. To enable
+ or disable the integration, click <menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Options</guimenuitem>
</menuchoice>, open the Version Control integration page, and choose the
- option, <option>None</option>. If for some reason ClearCase still uses
- WinMerge for diff operations, try one of these methods:</para>
-
- <itemizedlist>
- <listitem>
- <para>Replace the ClearCase <filename>map</filename> file created by
- the WinMerge installer with the <filename>map.bak</filename> backup
- file or </para>
- </listitem>
-
- <listitem>
- <para>Edit the ClearCase <filename>map</filename> file to run
- <filename>cleardiff.exe</filename> for the <command>cleartool
- diff</command> command. </para>
- </listitem>
- </itemizedlist>
+ appropriate option.</para>
+
+ <example>
+ <title>Visual Source Safe integration</title>
+
+ <para>Here is a sample file checkout using the VSS integration.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Launch a WinMerge file or folder comparison whose left or
+ right target is under version control.</para>
+ </listitem>
+
+ <listitem>
+ <para>In WinMerge, edit a version-controlled file.</para>
+ </listitem>
+
+ <listitem>
+ <para>Save your changes. WinMerge detects that the file is
+ read-only, and assumes that it is under Visual Source Safe version
+ control. WinMerge opens a Visual Source Save dialog, like
+ this:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/sourcesafe1.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </listitem>
+
+ <listitem>
+ <para>In the <guilabel>Database</guilabel> dropdown list, choose the
+ correct Visual SourceSafe database if there is more than one on your
+ system.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <guilabel>Project</guilabel> field shows the selected
+ file's location relative to the Visual SourceSafe database path.
+ Verify that the path is correct: most errors are caused by the wrong
+ project path. If you change folders, remember to change the project
+ path, too!</para>
+ </listitem>
+
+ <listitem>
+ <para>Enter your password if required. WinMerge remembers your
+ password for the current session, but for your security does not
+ store it. Therefore, you don't need to retype the password during a
+ session, but you must retype the password each time you open
+ WinMerge.</para>
+ </listitem>
+
+ <listitem>
+ <para>Optionally, enable one or both of these options:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><guilabel>Link to Destination VSS
+ project</guilabel></para>
+ </listitem>
+
+ <listitem>
+ <para><guilabel>Apply to all items</guilabel>. This option
+ enables you to check out multiple files in a single directory
+ when you copy files in a folder compare operation.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </orderedlist>
+
+ <para>Unfortunately, VSS provides very little information about error
+ conditions beyond the fact that they occur. If an operation fails,
+ causes might include any of the following conditions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Another user might have the file checked out with exclusive
+ access.</para>
+ </listitem>
+
+ <listitem>
+ <para>You might have specified the wrong project.</para>
+ </listitem>
+
+ <listitem>
+ <para>You might have entered the project name incorrectly.</para>
+ </listitem>
+
+ <listitem>
+ <para>You might not have used a valid VSS path (for example, this is
+ incorrect: <userinput>$/MyProject/res</userinput>).</para>
+ </listitem>
+
+ <listitem>
+ <para>Your connection to the VSS server computer might be
+ broken.</para>
+ </listitem>
+ </itemizedlist>
+ </example>
</section>
<section>
- <title>Tortoise SVN integration: example</title>
+ <title>Using WinMerge as a version control system's diff tool</title>
<indexterm>
<primary>TortoiseSVN integration</primary>
</indexterm>
- <para>TortoiseSVN is a Windows client for Subversion (SVN), an open source
- version control system. TortoiseSVN provides its own diff utility. The
- WinMerge integration with this VCS enables you to use WinMerge to compare
- files instead of the TortoiseSVN diff tool.</para>
-
- <para>One of the main uses of TortoiseSVN's diff is to see the most recent
- changes to a file that is under version control: that is, a file that you
- have checked out into a working copy. The following procedure illustrates
- such an operation using the WinMerge integration with TortoiseSVN. The
- integration with TortoiseCVS is similar.</para>
-
- <orderedlist>
- <listitem>
- <para>In Windows Explorer, navigate to a Subversion working copy that
- you have checked out.</para>
- </listitem>
-
- <listitem>
- <para>Right-click a file that is under Subversion management (usually
- indicated by a distinct TortoiseSVN icon), and click
- <guimenu>TortoiseSVN</guimenu> in the context menu.</para>
-
- <itemizedlist>
- <listitem>
- <para>If the file has not been modified, the context menu contains
- the shortcut, <guimenuitem>Diff with previous
- version</guimenuitem>. This command compares the checked-out
- version of the file with the previous version that was checked in
- to the repository.</para>
- </listitem>
-
- <listitem>
- <para>If you have modified the file, the context menu contains the
- same <guimenuitem>Diff with previous version</guimenuitem>
- shortcut, plus the <guimenuitem>Diff</guimenuitem> shortcut. This
- command compares your revision to the current version (the one you
- checked out). It is useful for reviewing the changes you have
- made.</para>
- </listitem>
- </itemizedlist>
- </listitem>
-
- <listitem>
- <para>Choose either the <guimenuitem>Diff with previous
- version</guimenuitem> or <guimenuitem>Diff</guimenuitem> shortcut. The
- WinMerge window opens, with the target file versions loaded In the
- File Compare window.</para>
- </listitem>
- </orderedlist>
-
- <para>The <menuchoice>
- <guimenu>TortoiseSVN</guimenu>
-
- <guimenuitem>Diff</guimenuitem>
- </menuchoice> shortcut is available for comparing any two files in your
- file system, not just files that are managed by Subversion. To illustrate
- how the WinMerge integration works in this case:</para>
-
- <orderedlist>
- <listitem>
- <para>In Windows Explorer, hold <keycap>Ctrl</keycap>, select any two
- files, and right-click.</para>
- </listitem>
-
- <listitem>
- <para>Choose <menuchoice>
- <guimenu>TortoiseSVN</guimenu>
-
- <guimenuitem>Diff</guimenuitem>
- </menuchoice> in the context menu.</para>
-
- <para>The WinMerge window opens, with the selected files loaded In the
- File Compare window.</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section>
- <title>Visual Source Safe integration: example</title>
-
- <indexterm>
- <primary>Visual SourceSafe integration</primary>
- </indexterm>
-
- <para>This example demonstrates a file checkout using the VSS
- integration.</para>
-
- <orderedlist>
- <listitem>
- <para>Launch a WinMerge file or folder comparison whose left or right
- target is under version control</para>
- </listitem>
-
- <listitem>
- <para>In WinMerge, edit a version-controlled file</para>
- </listitem>
-
- <listitem>
- <para>Save your changes. WinMerge detects that the file is read-only,
- and assumes that it is under Visual Source Safe version control.
- WinMerge opens a Visual Source Save dialog, like this:</para>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/sourcesafe1.png" format="PNG" />
- </imageobject>
- </mediaobject>
- </listitem>
-
- <listitem>
- <para>In the <guilabel>Database</guilabel> dropdown list, choose the
- correct Visual SourceSafe database if there is more than one on your
- system.</para>
- </listitem>
-
- <listitem>
- <para>The <guilabel>Project</guilabel> field shows the selected file's
- location relative to the Visual SourceSafe database path. Verify that
- the path is correct: most errors are caused by the wrong project path.
- If you change folders, remember to change the project path,
- too!</para>
- </listitem>
-
- <listitem>
- <para>Enter your password if required. WinMerge remembers your
- password for the current session, but for your security does not store
- it. Therefore, you don't need to retype the password during a session,
- but you must retype the password each time you open WinMerge.</para>
- </listitem>
-
- <listitem>
- <para>Optionally, enable one or both of these options:</para>
-
- <itemizedlist>
- <listitem>
- <para><guilabel>Link to Destination VSS project</guilabel></para>
- </listitem>
-
- <listitem>
- <para><guilabel>Apply to all items</guilabel>. This option enables
- you to check out multiple files in a single directory when you
- copy files in a folder compare operation.</para>
- </listitem>
- </itemizedlist>
- </listitem>
- </orderedlist>
-
- <para>Unfortunately, VSS provides very little information about error
- conditions beyond the fact that they occur. If an operation fails, causes
- might include any of the following conditions:</para>
-
- <itemizedlist>
- <listitem>
- <para>Another user might have the file checked out with exclusive
- access.</para>
- </listitem>
-
- <listitem>
- <para>You might have specified the wrong project.</para>
- </listitem>
-
- <listitem>
- <para>You might have entered the project name incorrectly.</para>
- </listitem>
-
- <listitem>
- <para>You might not have used a valid VSS path (for example, this is
- incorrect: <userinput>$/MyProject/res</userinput>).</para>
- </listitem>
-
- <listitem>
- <para>Your connection to the VSS server computer might be
- broken.</para>
- </listitem>
- </itemizedlist>
+ <para>When you compare files in TortoiseSVN, TortoiseCVS, or Rational
+ ClearCase, you can have the VCS launch WinMerge instead of its native diff
+ utility. You can configure this integration only during <link
+ linkend="Installing_usinginstaller">WinMerge installation</link>.</para>
+
+ <example>
+ <title>Tortoise SVN integration</title>
+
+ <para>Here is a sample diff operation in TortoiseSVN that uses the
+ WinMerge integration. The integrations with TortoiseCVS and ClearCase
+ are similar.</para>
+
+ <orderedlist>
+ <listitem>
+ <para>In Windows Explorer, navigate to a Subversion working copy
+ that you have checked out.</para>
+ </listitem>
+
+ <listitem>
+ <para>Right-click a file that is under Subversion management
+ (usually indicated by a distinct TortoiseSVN icon), and click
+ <guimenu>TortoiseSVN</guimenu> in the context menu.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If the file has not been modified, the context menu
+ contains the shortcut, <guimenuitem>Diff with previous
+ version</guimenuitem>. This command compares the checked-out
+ version of the file with the previous version that was checked
+ in to the repository.</para>
+ </listitem>
+
+ <listitem>
+ <para>If you have modified the file, the context menu contains
+ the same <guimenuitem>Diff with previous version</guimenuitem>
+ shortcut, plus the <guimenuitem>Diff</guimenuitem> shortcut.
+ This command compares your revision to the current version (the
+ one you checked out). It is useful for reviewing the changes you
+ have made.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Choose either the <guimenuitem>Diff with previous
+ version</guimenuitem> or <guimenuitem>Diff</guimenuitem> shortcut.
+ The WinMerge window opens, with the target file versions loaded In
+ the File Compare window.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The <menuchoice>
+ <guimenu>TortoiseSVN</guimenu>
+
+ <guimenuitem>Diff</guimenuitem>
+ </menuchoice> shortcut is available for comparing any two files in
+ your file system, not just files that are managed by Subversion. To
+ illustrate how the WinMerge integration works in this case:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>In Windows Explorer, hold <keycap>Ctrl</keycap>, select any
+ two files, and right-click.</para>
+ </listitem>
+
+ <listitem>
+ <para>Choose <menuchoice>
+ <guimenu>TortoiseSVN</guimenu>
+
+ <guimenuitem>Diff</guimenuitem>
+ </menuchoice> in the context menu.</para>
+
+ <para>The WinMerge window opens, with the selected files loaded In
+ the File Compare window.</para>
+ </listitem>
+ </orderedlist>
+ </example>
+
+ <section id="VersionControl_cc">
+ <title>About the ClearCase integration</title>
+
+ <para>When you choose the integration option for Rational ClearCase
+ during WinMerge installation, the installer:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Creates a backup copy of the ClearCase
+ <filename>map</filename> file, <filename>map.bak</filename>, in the
+ <filename><replaceable>ccase-home-dir</replaceable>\lib\mgrs</filename>
+ directory. The <filename>map</filename> file is a user-configurable
+ file that associates ClearCase methods with the programs that carry
+ them out.</para>
+ </listitem>
+
+ <listitem>
+ <para>Modifies the <guilabel>text_file_delta</guilabel> field In the
+ <filename>map</filename> file, specifying WinMerge instead of the
+ default <filename>cleardiff.exe</filename> when running the
+ <command>cleartool diff</command> command.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>If you later want to disable WinMerge interactions with ClearCase,
+ replace the ClearCase <filename>map</filename> file created by the
+ WinMerge installer with the <filename>map.bak</filename> backup file.
+ Alternatively, edit the ClearCase <filename>map</filename> file to run
+ <filename>cleardiff.exe</filename> for the <command>cleartool
+ diff</command> command.</para>
+ </section>
</section>
</section>
</article>
\ No newline at end of file