<?xml version="1.0" encoding="UTF-8"?>
<article id="Quick_start">
  <title>Quick start</title>

  <section>
    <title><indexterm>
        <primary>getting started with WinMerge</primary>
      </indexterm><indexterm>
        <primary>choosing files and folders</primary>

        <secondary>getting started</secondary>
      </indexterm>Selecting files and folders to compare</title>

    <para>After you have installed WinMerge, step through the procedure and
    discussions in this topic to learn basic WinMerge operations and concepts.
    The methods shown are not the only ways to do things: there are usually
    several ways to do each task. When you are done, you can go on to learn
    other methods and more advanced skills, which are covered in other help
    topics.</para>

    <orderedlist>
      <listitem>
        <para>Open the WinMerge window. Here are some of the methods you can
        use:<indexterm>
            <primary>WinMerge window</primary>
          </indexterm></para>

        <itemizedlist>
          <listitem>
            <para>Double-click the WinMerge desktop shortcut.</para>
          </listitem>

          <listitem>
            <para>Navigate to the WinMerge launcher in your Start menu.</para>
          </listitem>

          <listitem>
            <para>In a Command Prompt window, cd to the WinMerge installation
            folder and enter <command>WinMergeU</command>.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>In the WinMerge window select the files or folders that you want
        to operate on. For example:</para>

        <itemizedlist>
          <listitem>
            <para>Click <menuchoice>
                <guimenu>File</guimenu>

                <guimenuitem>Open</guimenuitem>
              </menuchoice>.</para>
          </listitem>

          <listitem>
            <para>Click the <inlinemediaobject>
                <imageobject>
                  <imagedata contentwidth="16"
                             fileref="screenshots/open_icon.png" />
                </imageobject>

                <textobject>
                  <phrase>WinMerge open button</phrase>
                </textobject>
              </inlinemediaobject> Open tool bar button.</para>
          </listitem>

          <listitem>
            <para>Press <keycombo>
                <keycap>Ctrl</keycap>

                <keycap>O</keycap>
              </keycombo>.</para>
          </listitem>
        </itemizedlist>

        <para><indexterm>
            <primary>Select Files or Folders dialog</primary>

            <secondary>getting started</secondary>
          </indexterm>The Select Files or Folders dialog opens:</para>

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

          <textobject>
            <phrase>Select Files or Folders window</phrase>
          </textobject>
        </mediaobject>
      </listitem>

      <listitem>
        <para>In the <guilabel>1st</guilabel> and <guilabel>2nd</guilabel>
        fields, specify the files and folders to compare. Use any of these
        methods:</para>

        <para><itemizedlist>
            <listitem>
              <para>Enter the path names directly into the fields.</para>
            </listitem>

            <listitem>
              <para>Click the <guibutton>Browse</guibutton> button to navigate
              to the desired path.</para>

              <para>In the Open dialog, the text, <literal>Folder
              Selection</literal>, is initially displayed in the <guilabel>File
              name</guilabel> field. Your selection depends on the type of
              comparison you want to do:</para>

              <itemizedlist>
                <listitem>
                  <para>If you are comparing files, select the target file. The
                  <literal>Folder Selection</literal> text is overwritten with
                  your selection.</para>
                </listitem>

                <listitem>
                  <para>If you are comparing folders, open the target folder; do
                  not select a file. The <literal>Folder Selection</literal>
                  text remains in place.</para>
                </listitem>
              </itemizedlist>

              <para>Click <guibutton>Open</guibutton> to dismiss the Open dialog
              and load your selection in the <guilabel>1st</guilabel> or
              <guilabel>2nd</guilabel> field. If you specified folders, the
              field includes a backslash ( \ ) at end of the path.</para>
            </listitem>

            <listitem>
              <para>Click the combo box and choose a previously-used
              path.</para>

              <tip>
                <para>To make it easier to select frequently-used paths,
                consider enabling the <guilabel>Open-dialog
                Auto-completion</guilabel> option. With this option, WinMerge
                shows a list of paths available as you type in the fields. See
                <xref linkend="Configuration" /> for details.</para>
              </tip>
            </listitem>

            <listitem>
              <para>Drag and drop a file or folder into the dialog or the
              <guilabel>1st</guilabel> or <guilabel>2nd</guilabel>
              field.</para>
            </listitem>
          </itemizedlist></para>

        <para><note>
            <para>You can select only one pair of files or one pair of folders
            to compare. If you select a file and a folder or if one of the files
            or folders is not found, WinMerge disables the
            <guibutton>Compare</guibutton> button in the dialog.</para>

            <para>The status message at the bottom of the dialog also informs
            you if one of the paths is invalid.</para>
          </note></para>
      </listitem>

      <listitem>
        <para>If you are comparing folders, you can use the
        <guilabel>Filter</guilabel> field to eliminate some files from the
        operation. The field specifies a subset of files in the selected paths
        that are to be included; all unspecified files are excluded.</para>

        <para>You can enter file masks to filter files with certain extensions.
        For example, this expression includes only C and C++ source files; all
        other file types are eliminated from your selection.</para>

        <para><filename><userinput>*.cpp;*.hpp;*.c;*.h</userinput></filename></para>

        <para>For more robust filtering, enter a filter file instead of file
        masks: click the <guibutton>Select</guibutton> button next to the
        <guilabel>Filters</guilabel> field to choose from a list of available
        filters. File filters contain any number of rules to either include or
        exclude files. WinMerge installs a set of filter files, which you can
        edit or augment with your own files.</para>

        <para>See <xref linkend="Filters" /> for full details about file masks
        and filter files.</para>

        <!--
        <variablelist>
          <varlistentry>
            <term>File masks</term>

            <listitem>
              <para>In this method, you specify the types of files to include in
              the operation; all other files are excluded (filtered). With no
              file mask or the default mask of <literal>*.*</literal>, all files
              in the paths are included, so no filtering is performed. To add
              filtering, enter one or more masks. Separate multiple masks with
              spaces, commas, colons or semicolons.</para>

              <para>For example, this expression filters all files from the
              operation except C and C++ source files:</para>

              <para><filename><userinput>*.cpp;*.hpp;*.c;*.h</userinput></filename></para>

              <para>File names cannot be filtered: they are represented in the
              masks only by the <literal>*</literal> wildcard character. For
              example, these expressions are not valid masks:</para>

              <para><userinput>mybook.xml</userinput></para>

              <para><userinput>yourbook.*</userinput></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>File filtering</term>

            <listitem>
              <para>File filtering is more powerful than extension filtering.
              Click the <guibutton>Select</guibutton> button next to the
              <guilabel>Filters</guilabel> field to choose from a list of
              available filters. </para>
            </listitem>
          </varlistentry>
        </variablelist>
-->
      </listitem>

      <listitem>
        <para>The <guilabel>Include Subfolders</guilabel> check box provides
        another way to control the scope of folder comparisons. If you check
        this option, WinMerge recursively compares subfolders, and shows all the
        files and folders it finds in one view. If you disable the option, only
        the current folder is compared, and subfolders are listed by name
        (without their contents), so you can browse into them.</para>
      </listitem>

      <listitem>
        <para>The Unpacker field enables you to perform compare operations on
        plug-ins.</para>
      </listitem>
    </orderedlist>

    <section>
      <title>Other ways to open files and folders<indexterm>
          <primary>project files</primary>
        </indexterm><indexterm>
          <primary>command line</primary>

          <secondary>opening files and folders</secondary>
        </indexterm></title>

      <para>The Select Files or Folders dialog is the main interface for opening
      files and folders. But you can use many other ways, too:</para>

      <itemizedlist>
        <listitem>
          <para><xref linkend="OpenPaths_project" /> are the easiest and fastest
          way to open frequently used paths. To open a project file, use one of
          these methods:</para>

          <itemizedlist>
            <listitem>
              <para>From the WinMerge window, click <menuchoice>
                  <guimenuitem>File</guimenuitem>

                  <guimenuitem>Open Project</guimenuitem>
                </menuchoice>.</para>
            </listitem>

            <listitem>
              <para>From a command line.</para>
            </listitem>

            <listitem>
              <para>From the Opening Files and Folders dialog, specify a project
              file in the <guilabel>1st</guilabel> field.</para>

              <note>
                <para>If you specify project files in both the
                <guilabel>1st</guilabel> and <guilabel>2nd</guilabel> fields,
                WinMerge does not open either project file; it simply compares
                the XML content of the two files.</para>
              </note>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <simpara><xref linkend="OpenPaths_shell-integ" />.</simpara>
        </listitem>

        <listitem>
          <simpara>Use the <xref linkend="Command_line" /> interface to start
          WinMerge from other applications, from a command prompt, or a batch or
          script file.</simpara>
        </listitem>

        <listitem>
          <simpara>Drag and drop files and folders directly into the WinMerge
          window or on the WinMerge desktop shortcut.</simpara>
        </listitem>
      </itemizedlist>
    </section>
  </section>

  <section>
    <title><indexterm>
        <primary>comparing folders</primary>

        <secondary>getting started</secondary>
      </indexterm><indexterm>
        <primary>Folder Compare window</primary>

        <secondary>getting started</secondary>
      </indexterm>Comparing folders</title>

    <para>If you selected two folders in the Open dialog, the Folder Compare
    window is opened. The Folder Compare window is a tabular list of items found
    in the compared folders. Each row displays information about a found file,
    with the file name in the left column and additional information in the
    other columns:</para>

    <mediaobject>
      <imageobject>
        <imagedata contentwidth="600" fileref="screenshots/foldercomp1.png"
                   format="PNG" />
      </imageobject>

      <textobject>
        <phrase>Folder Compare window</phrase>
      </textobject>
    </mediaobject>

    <para>WinMerge does not have a concept of <wordasword>original</wordasword>
    and <wordasword>changed</wordasword> sides. Instead, it simply shows what is
    different between two selected folders. A file or folder that is found only
    on one side is simply shown as a unique item on that side, not as added or
    removed. For example, in the <guilabel>Comparison result </guilabel>column
    of the preceding figure, <filename>Merge.aps</filename> and
    <filename>Merge.rc.bak</filename> are each found in only one of the compared
    folders.</para>

    <para>You can manage files and folders in many ways using the
    <guimenu>Merge</guimenu> menu, toolbar buttons, or context (right-click)
    menu. The most important action is making files or folders identical in both
    sides by selecting one of several Copy items. When you copy a file or folder
    to other side, the Comparison result value changes to
    <literal>Identical</literal>.</para>

    <para>If a file or folder exists in both sides (and it is not a binary file)
    it can be opened for file comparison using one of these
    methods:<itemizedlist>
        <listitem>
          <simpara>Click <menuchoice>
              <guimenuitem>Compare</guimenuitem>

              <guimenuitem>Merge</guimenuitem>
            </menuchoice> in the WinMerge menu.</simpara>
        </listitem>

        <listitem>
          <simpara>Right-click the row and choose the
          <guimenuitem>Compare</guimenuitem> shortcut.</simpara>
        </listitem>

        <listitem>
          <simpara>Double-click the row.</simpara>
        </listitem>

        <listitem>
          <simpara>Select the row and press <keycap>Enter</keycap>.</simpara>
        </listitem>
      </itemizedlist>If you compare a subfolder, the new folder's comparison
    table is loaded in the current Folder Compare window . When you are done
    with that folder's comparison, you can navigate back to its parent folder by
    double-clicking the <inlinemediaobject>
        <imageobject>
          <imagedata contentwidth="23" fileref="screenshots/nav_uparrow_btn.png" />
        </imageobject>

        <textobject>
          <phrase>Navigator up arrow button</phrase>
        </textobject>
      </inlinemediaobject> up arrow at the top of the Filename column.</para>

    <para>If you compare a file, WinMerge opens the File Compare window,
    described in the next section. If you change a file in the File Compare
    window, and then return to the Folder Compare window, you will see the
    file's data is updated there.</para>
  </section>

  <section id="QuickStart_comparingfiles">
    <title><indexterm>
        <primary>comparing files</primary>

        <secondary>getting started</secondary>
      </indexterm><indexterm>
        <primary>File Compare window</primary>

        <secondary>getting started</secondary>
      </indexterm>Comparing files</title>

    <mediaobject>
      <imageobject>
        <imagedata contentwidth="600" fileref="screenshots/filecomp1.png"
                   format="PNG" />
      </imageobject>

      <textobject>
        <phrase>File Compare window</phrase>
      </textobject>
    </mediaobject>

    <para>The File Compare window shows the two selected files side by side, in
    separate File panes. Different lines are highlighted with a background
    color. One or more consecutive different lines form one difference (or
    <glossterm>diff</glossterm>). In the preceding example, a single difference
    is selected in the File panes and displayed by itself in the Diff Pane.
    WinMerge mainly works with these differences, not separate lines. When you
    merge a difference, you copy all of its lines from one side to the
    other.</para>

    <para><important>
        <para>Notice how WinMerge fills missing lines, so that similar lines are
        always aligned vertically, side by side. This is different from most
        other compare/merge programs, and can take a while to learn.</para>
      </important></para>

    <para>WinMerge has a simple integrated editor that features basic typing,
    copying, cutting and pasting of text. If <guilabel>Automatic
    rescan</guilabel> is enabled, WinMerge updates file differences while you
    edit a file. If <guilabel>Automatic rescan</guilabel> is disabled, you can
    update files by selecting <menuchoice>
        <guimenu>Edit</guimenu>

        <guimenuitem>Refresh</guimenuitem>
      </menuchoice>, clicking the <inlinemediaobject>
        <imageobject>
          <imagedata contentwidth="16" fileref="screenshots/refresh_btn.png" />
        </imageobject>

        <textobject>
          <phrase>Refresh button</phrase>
        </textobject>
      </inlinemediaobject> toolbar button, or pressing
    <keycap>F5</keycap>.</para>
  </section>
</article>
