<?xml version="1.0" encoding="UTF-8"?>
<article id="Open_paths">
  <title>Opening files and folders<indexterm>
      <primary>opening files and folders</primary>
    </indexterm></title>

  <para>WinMerge provides several ways to specify paths and open files or
  folders:<indexterm>
      <primary>folders</primary>

      <secondary>selecting in Select Files or Folders dialog</secondary>
    </indexterm><indexterm>
      <primary>files</primary>

      <secondary>selecting in Select Files or Folders dialog</secondary>
    </indexterm></para>

  <itemizedlist>
    <listitem>
      <para><xref linkend="OpenPaths_opendialog" /></para>
    </listitem>

    <listitem>
      <para><xref linkend="OpenPaths_shell-integ" /></para>
    </listitem>

    <listitem>
      <para><xref linkend="OpenPaths_dragndrop" /></para>
    </listitem>

    <listitem>
      <para><xref linkend="OpenPaths_project" /></para>
    </listitem>
  </itemizedlist>

  <section id="OpenPaths_opendialog">
    <title>Select Files or Folders dialog<indexterm>
        <primary>Select Files or Folders dialog</primary>
      </indexterm></title>

    <para><xref linkend="Quick_start" /> describes the Select Files or Folders
    dialog. This section provides more details, and some tips for using the
    Select Files or Folders dialog more efficiently.</para>

    <section>
      <title>Using environment variables<indexterm>
          <primary>environment variables, in compare target paths</primary>
        </indexterm></title>

      <para>You can use environment variables in your paths. Windows expands the
      variable name between % (percent) delimiters. For example, if an
      environment variable named <envar>WORKDIR</envar> has the value <filename
      class="directory">c:\workfiles</filename>, then the path
      <envar>%WORKDIR%\project1</envar> is expanded to <filename
      class="directory">c:\workfiles\project1</filename> .</para>
    </section>

    <section id="OpeningArchives">
      <title>Opening archive files<indexterm>
          <primary>7-Zip archives</primary>

          <secondary>opening</secondary>
        </indexterm></title>

      <para>WinMerge archive support is provided in the 7-Zip plugin. See <xref
      linkend="Install" /> to install this plugin.</para>

      <para>Opening two archive files is similar to opening normal files:
      specify two archive files in the Open-dialog's <guilabel>1st</guilabel>
      and <guilabel>2nd</guilabel> fields. If WinMerge recognizes the archive
      format, it opens the contents of the archive files in the Folder Compare
      window.</para>

      <para>The <xref linkend="Compare_dirs" /> topic describes how to work with
      archive files. For example, if an archive file contains two subfolders
      named <filename class="directory">Original/</filename> and <filename
      class="directory">Altered/</filename>, you can compare the contents of the
      two subfolders by specifying the same archive file in both sides in the
      Select Files or Folders dialog or WinMerge command line.</para>

      <tip>
        <para>When you drag an archive file to the WinMerge window, press
        <keycap>Shift</keycap> when dropping the file: WinMerge automatically
        copies the same filename to both sides and opens the archive
        file.</para>
      </tip>
    </section>

    <section id="Open_paths_filters">
      <title>Applying filters<indexterm>
          <primary>filters</primary>

          <secondary>applying in Select Files or Folders dialog</secondary>
        </indexterm></title>

      <para>The <guilabel>Filter</guilabel> edit field enables you to restrict
      the files to be included in your folder compare. You can specify one or
      more file masks, or a single file filter (not both).</para>

      <para>A mask is a simple expression based on file extensions. For example,
      this list of file masks includes only files with the specified extensions;
      all others are excluded from the selection when the compare operation
      starts:</para>

      <screen>*.h;*.cpp;*.txt,*.ini</screen>

      <para>File masks are practical for simple filtering; for more advanced
      selecting, use filter files. Filter files are collections of regular
      expressions that can either include or exclude files. WinMerge installs a
      number of predefined filter files in its <filename>Filters</filename>
      folder, and you can create your own, too.</para>

      <para>To specify a filter, click the <guibutton>Select</guibutton> button
      next to the <guilabel>Filters</guilabel> field to choose from a list of
      available filters. Or, click the Filter drop-down list and choose a
      recently-used filter file.</para>

      <para>For full information about filter masks and filter files, see <xref
      linkend="Filters" />.</para>
    </section>

    <section id="Open_paths_unpacker">
      <title>Selecting an unpacker for file comparisons<indexterm>
          <primary>unpacker plugins</primary>
        </indexterm></title>

      <para>Unpackers are plugins that are installed with WinMerge to provide
      functionality that is not used by default. Plugins that can be used to
      preprocess certain types of files before comparing them. For example,
      WinMerge cannot normally compare MS Word doc files, but by unpacking them,
      you can compare just the text contents. See <xref linkend="Plugins" /> for
      details.</para>

      <para>To apply a plugin to your file comparison, click the
      <guibutton>Select</guibutton> button for the <guilabel>Unpacker</guilabel>
      option. In the Select Unpacker dialog:</para>

      <xi:include href="select_unpacker.xml"
                  xmlns:xi="http://www.w3.org/2001/XInclude"
                  xpointer="element(select-unpacker-proc)" />

      <para>Your choice is displayed in the <guilabel>Unpacker</guilabel> field.
      Note that you cannot select an unpacker when launching a Folder Compare
      operation.</para>
    </section>
  </section>

  <section id="OpenPaths_shell-integ">
    <title><indexterm>
        <primary>Windows shell integration</primary>
      </indexterm><indexterm>
        <primary>context menu, WinMerge shortcuts in Windows Explorer</primary>
      </indexterm>Launching WinMerge operations in Windows Explorer</title>

    <para>The optional Windows shell integration enables you to run WinMerge
    compare operations directly from Windows Explorer, using WinMerge shortcuts
    in the context menu.</para>

    <!--WinMerge provides two optional types of integration with Windows Explorer. The first type lets you launch WinMerge compare operations directly from Windows Explorer, skipping the Select Files or Folders dialog. The second type lets you run Windows shell commands from the WinMerge window.-->

    <section>
      <title>Enabling the Windows Explorer integration</title>

      <para>The Windows Explorer shell integration is available only if enabled.
      You can enable it either <link linkend="Installing_usinginstaller">during
      WinMerge installation</link> or later, using the <xref
      linkend="Configuration_shell-integ" /> in the Options window. In the
      Options window, configure the <option>Add to context menu</option> option,
      including its suboptions if you like.</para>
    </section>

    <section>
      <title>Using the WinMerge shortcut</title>

      <para>If you enable <option>Add to context menu</option> without the
      advanced menu suboption, the <guimenuitem>WinMerge</guimenuitem> shortcut
      is added to the Explorer context menu. For example:</para>

      <para>To use the basic shell integration, begin by selecting two paths in
      Windows Explorer. Then, right-click and choose WinMerge in the context
      menu. For example:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="screenshots/ctx_menu_simple.png" format="PNG" />
        </imageobject>

        <textobject>
          <phrase>WinMerge command in Windows Explorer context menu</phrase>
        </textobject>
      </mediaobject>

      <para>WinMerge opens the paths directly in the File Compare or Folder
      Compare window.</para>

      <para>The left and right sides are determined by the sort order in Windows
      Explorer. In the preceding screenshot, the Windows Explorer file list is
      in ascending order, so WinMerge opens with <filename>File2</filename> on
      the 1st side and <filename>File1</filename> on the 2nd..</para>

      <note>
        <para>If either path cannot be opened for any reason, WinMerge opens the
        Select Files or Folders dialog, where you can specify new paths.
        Similarly, if you select only a single path, the Select Files or Folders
        dialog opens with the selected file or folder in the
        <guilabel>1st</guilabel> field, leaving the <guilabel>2nd</guilabel>
        path for you to specify.</para>
      </note>

      <para>The <guimenuitem>WinMerge</guimenuitem> shortcut is quick and easy
      to use, but you can compare only files or folders that you are able to
      select concurrently in Windows Explorer. For more flexible selections,
      consider enabling the advanced menu, described in the next section.</para>
    </section>

    <section>
      <title>Using the advanced menu</title>

      <para>If you choose the <option>Enable advanced menu</option>, the
      <guimenuitem>WinMerge</guimenuitem> shortcut is replaced with two
      <guimenuitem>Compare</guimenuitem> shortcuts:</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="screenshots/ctx_menu_advanced.png" format="PNG" />
        </imageobject>

        <textobject>
          <phrase>Advanced WinMerge context menu</phrase>
        </textobject>
      </mediaobject>

      <para>Use the <guimenuitem>Compare</guimenuitem> shortcuts in this
      order:</para>

      <orderedlist>
        <listitem>
          <para>Right-click the first path and choose <guimenuitem>Compare
          To</guimenuitem>. WinMerge stores the path in memory until you select
          the second path.</para>
        </listitem>

        <listitem>
          <para>If you decide that you have chosen the wrong first path, you can
          change it before choosing the second path:</para>

          <para>Right-click the new path and choose the <guimenuitem>Re-select
          First</guimenuitem> shortcut. The new selection overrides your
          previous path, and you can go on to the next step.</para>
        </listitem>

        <listitem>
          <para>Navigate to the second file or folder that you want to compare.
          The second path can be in any folder, or even in a different Windows
          Explorer window from the first path. Right-click the second path and
          choose <guimenuitem>Compare</guimenuitem>.</para>

          <para>WinMerge opens the File Compare or Folder Compare window,
          loading the first and second paths in the 1st and 2nd sides,
          respectively.</para>
        </listitem>
      </orderedlist>

      <note>
        <para>If you click <guimenuitem>Compare</guimenuitem> before designating
        the first path, the Select Files or Folders dialog is opened, with your
        selection as the first (<guilabel>1st</guilabel>) path. Specify the
        second path in the <guilabel>2nd</guilabel> field to continue with the
        comparison.</para>
      </note>

      <!--              <tip><para>When you use this method, take advantage 
of the Select Files or Folders dialog's MRU list. This is very handy when you need 
to compare one file/folder against several files/folders.</para> </tip> -->

      <para>The <guimenuitem>Compare To</guimenuitem> paths is stored in memory
      until WinMerge is opened. As a result, you don't need to select both files
      at the same time or even using the same Windows Explorer view: you can
      choose one, open a different directory, and choose the other one. Both
      paths are discarded from memory after a compare operation. This means that
      you cannot select one <guimenuitem>Compare To</guimenuitem> path and
      compare it against several paths.</para>
    </section>

    <section>
      <title>Including subfolders when using the Windows Explorer
      integration<indexterm>
          <primary>recursive folder compare</primary>

          <secondary>specifying in Select Files or Folders dialog</secondary>
        </indexterm><indexterm>
          <primary>subfolders</primary>

          <seealso>recursive folder compare</seealso>
        </indexterm></title>

      <para>By default, folder compares that you do using the
      <guimenuitem>WinMerge</guimenuitem> or <guimenuitem>Compare</guimenuitem>
      shortcut are recursive.
      There is a way to launch non-recursive compares with the Windows Explorer
      integration:</para>

      <itemizedlist>
        <listitem>
          <para>Disable <guilabel>Include Subfolders</guilabel> in the
          Folder page of the WinMerge Options dialog.</para>
        </listitem>
      </itemizedlist>

      <tip>
        <para>Press <keycap>Ctrl</keycap> while selecting the
        <guimenuitem>WinMerge</guimenuitem> or
        <guimenuitem>Compare</guimenuitem> shortcut in the Windows Explorer
        context menu to force a reverse comparison with the current 'Include Subfolders' settings.</para>
      </tip>
    </section>
  </section>

  <section id="OpenPaths_dragndrop">
    <title><indexterm>
        <primary>drag and drop, in WinMerge window</primary>
      </indexterm>Using Drag and drop</title>

    <para>From any Windows source that allows you to drag objects, such as
    Windows Explorer or the Desktop, you can drag and drop one or two paths into
    the WinMerge window. If you drop only one path into WinMerge, the Select
    Files or Folders dialog opens for you to select the second path. If the
    single path specifies a project file, then the project file is
    opened.</para>

    <para>By default, WinMerge does include subfolders in compare
    operations. To not include subfolders, press and hold <keycap>Ctrl</keycap>
    while dropping paths. Another useful key when dropping paths is
    <keycap>Shift</keycap>: To open the same path in both sides of a Compare
    window, press and hold <keycap>Shift</keycap> while dropping only one path.
    This is a handy way to open archive files (see <xref
    linkend="OpeningArchives" />).</para>

    <para>You can drop paths into the Select Files or Folders dialog. A typical
    procedure is to drag and drop the first path into the WinMerge window, and
    then drag and drop the second path into the Select Files or Folders dialog.
    When a path is dropped into the Select Files or Folders dialog, it is loaded
    into either the 1st or 2nd path field:</para>

    <variablelist>
      <varlistentry>
        <term>1st</term>

        <listitem>
          <para>If the 1st field is empty or both path fields already contain
          paths</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>2nd</term>

        <listitem>
          <para>If the 1st path is not empty and the 2nd path is empty</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="OpenPaths_project">
    <title><indexterm>
        <primary>project files</primary>
      </indexterm><indexterm>
        <primary>command line</primary>

        <secondary>specifying project files</secondary>
      </indexterm>Project files</title>

    <para>You can save the currently open paths and filters in a project file.
    Then, you can easily open the project later to compare the same files.
    Project files are handy if you compare the same files repeatedly.</para>

    <section>
      <title>Using project files</title>

      <para>To use a project file In the WinMerge window, click <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Open Project</guimenuitem>
        </menuchoice>. WinMerge reads the paths from the project file. If the
      project file has two or three paths, two respective three paths are
      opened. If only one path is given or one of paths is invalid, WinMerge
      opens the Select Files or Folders dialog, where you can add or correct the
      path information. Here are a few things to consider:</para>

      <itemizedlist>
        <listitem>
          <simpara>If you specify two project files, the project files
          themselves are compared.</simpara>
        </listitem>

        <listitem>
          <simpara>If you specify a project file as the left file but do not
          specify a right file, the single project file is opened as if you had
          used the <menuchoice>
              <guimenu>File</guimenu>

              <guimenuitem>Open Project</guimenuitem>
            </menuchoice> command.</simpara>
        </listitem>

        <listitem>
          <simpara>If you specify a project file as the left file and any other
          file on the right side, the contents of the project file and the other
          file are compared.</simpara>
        </listitem>
      </itemizedlist>

      <para>To specify a project file on the command line, simply enter it as a
      single file path.</para>
    </section>

    <section>
      <title>Editing and saving project files</title>

      <para>To save a project file, click <menuchoice>
          <guimenu>File</guimenu>

          <guimenuitem>Save Project</guimenuitem>
        </menuchoice>. The <guilabel>Project File</guilabel> dialog provides
      fields and options that you can easily edit to build a project file. If a
      compare window is currently open, the <guilabel>Project File</guilabel>
      dialog is initialized with values from the current compare; otherwise, you
      provide the values yourself. To use an existing project, click
      <guibutton>Open</guibutton> and select a project to load its values (any
      existing values are overwritten in the dialog).</para>

      <para>When you finished editing, click <guibutton>Save</guibutton> to
      store the file.</para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="screenshots/projfile_save.png" format="PNG" />
        </imageobject>

        <textobject>
          <phrase>Project File dialog</phrase>
        </textobject>
      </mediaobject>
    </section>

    <section>
      <title>Project file format</title>

      <para>Project files are simple XML files with <filename
      class="extension">a .WinMerge</filename> extension. For example:</para>

      <screen>&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;project&gt;
   &lt;paths&gt;
      &lt;left&gt;c:\work\project1&lt;/left&gt;
      &lt;left-readonly&gt;1&lt;/left-readonly&gt;
      &lt;middle&gt;c:\work\project2&lt;/middle&gt;
      &lt;middle-readonly&gt;1&lt;/middle-readonly&gt;
      &lt;right&gt;c:\work\project3&lt;/right&gt;
      &lt;right-readonly&gt;0&lt;/right-readonly&gt;
      &lt;filter&gt;Visual C++ loose&lt;/filter&gt;
      &lt;subfolders&gt;0&lt;/subfolders&gt;
   &lt;/paths&gt;
&lt;/project&gt;</screen>

      <para>A project file contains a <sgmltag>paths</sgmltag> element that can
      contain one of each of these elements:</para>

      <variablelist>
        <varlistentry>
          <term><sgmltag>left</sgmltag></term>

          <listitem>
            <para>Left path to open</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>left-readonly</sgmltag></term>

          <listitem>
            <para>1 = Open read only</para>

            <para>0 = Open normally</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>middle</sgmltag></term>

          <listitem>
            <para>Middle path to open</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>middle-readonly</sgmltag></term>

          <listitem>
            <para>1 = Open read only</para>

            <para>0 = Open normally</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>right</sgmltag></term>

          <listitem>
            <para>Right path to open</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>right-readonly</sgmltag></term>

          <listitem>
            <para>1 = Open read only</para>

            <para>0 = Open normally</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>filter</sgmltag></term>

          <listitem>
            <para>File filter name or list of extensions</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><sgmltag>subfolders</sgmltag></term>

          <listitem>
            <para>0 = Subfolders not included</para>

            <para>1 = Subfolders included</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>None of the fields is required, and they can be empty (<literal>for
      example, &lt;left&gt;&lt;/left&gt; or &lt;left/&gt;</literal>).</para>
    </section>
  </section>
</article>
