<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="file-filters">
<info>
  <title type="sort">2</title>
  <link type="guide" xref="index#folder-mode"/>
  <revision docversion="1.6" status="draft"/>
  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  <credit type="author copyright">
    <name>Kai Willadsen</name>
    <email>kai.willadsen@gmail.com</email>
    <years>2012</years>
  </credit>
</info>
<title>Filtering out files</title>

<p>
When you compare folders, you may want to be able to ignore some files.
For example, you may wish to only see files that are present and different
in both folders, ignoring those that are the same or only exist in one
folder. Alternatively, you might want to ignore all the files in your
<file>.git</file> directory, or ignore all images.
</p>

<p>
<app>Meld</app> has several different ways of controlling which files
and what kind of differences you see. You can filter based on
<link xref="#file-state-filter">differences between a file across
folders</link> or <link xref="#file-name-filter">file and folder
names</link>. You can also tell <app>Meld</app> to treat filenames
as being <link xref="#file-case-filter">case insensitive</link>.
Finally, you can use <link xref="text-filters">text filters</link> to
change what both folder and file comparisons see.
</p>

<note style="important">
  <p>
  Any <link xref="text-filters">text filters</link> you've defined
  <em>automatically apply</em> when comparing folders. Files that are
  identical after all of the text filters are applied are not
  highlighted as being different, but are shown in italics.
  </p>
</note>



<section id="file-state-filter">
<title>File differences filtering</title>

<p>
In a folder comparison, each line contains a single file or folder
that is present in at least one of the folders being compared. Each of
these lines is classified as being either <em>Modified</em>, <em>New</em>
or <em>Same</em>:
</p>
<terms>
  <item>
    <title>Modified</title>
    <p>The file exists in multiple folders, but the files are different</p>
  </item>
  <item>
    <title>New</title>
    <p>The file exists in one folder but not in the others</p>
  </item>
  <item>
    <title>Same</title>
    <p>The file exists in all folders, and is the same everywhere</p>
  </item>
</terms>
<p>
You can change which types of differences you see in your current
comparison by using the <gui style="button">File Filters</gui>
button on the toolbar.
</p>

<note style="tip">
  <p>
  Currently, you can only filter files based on their state; folders
  can't be filtered in this way. For example, you can't tell
  <app>Meld</app> to ignore all folders that contain only new files. A
  folder containing only "New" files would show up as empty, but still
  present.
  </p>
</note>

</section>



<section id="file-name-filter">
<title>Filename filtering</title>

<p>
<app>Meld</app> comes with a useful set of filename filters that let you
ignore uninteresting files and folders like common backup files and the
metadata folders of version control systems. Each filename filter can be
separately activated or deactivated from the
<gui style="button">File Filters</gui> button on the toolbar.
</p>

<p>
You can add, remove or change filename filters from the
<gui style="tab">File Filters</gui> section of the <gui>Preferences</gui>
dialog. Filename filters specify patterns of filenames that will
<em>not</em> be looked at when performing a folder comparison. Any file
that matches an active filter won't even show up in the tree comparison.
Filename filters match both files and folders; if a folder matches
a filter, it and all of its contents are ignored.
</p>

<p>
Filename filters match according to shell glob patterns. For example,
<code>*.jpg</code> will match all filenames ending in <code>.jpg</code>.
The following table lists all of the shell glob characters that
<app>Meld</app> recognises.
</p>

<table frame="top bottom">
  <title>Shell glob patterns</title>

  <thead>
    <tr>
      <td><p>Wildcard</p></td><td><p>Matches</p></td>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><p><code>*</code></p></td>
      <td><p>anything (i.e., zero or more characters)</p></td>
    </tr>
    <tr>
      <td><p><code>?</code></p></td>
      <td><p>exactly one character</p></td>
    </tr>
    <tr>
      <td><p><code>[abc]</code></p></td>
      <td><p>any one of the listed characters</p></td>
    </tr>
    <tr>
      <td><p><code>[!abc]</code></p></td>
      <td><p>anything <em>except</em> one of the listed characters</p></td>
    </tr>
    <tr>
      <td><p><code>{cat,dog}</code></p></td>
      <td><p>either "cat" or "dog"</p></td>
    </tr>
  </tbody>
</table>

<note style="tip">
  <p>
  Changing a filter's <gui>Active</gui> setting in the
  <gui>Preferences</gui> dialog changes whether that filter is active
  <em>by default</em>.
  </p>

  <p>
  Activating a filter from the menu or the toolbar turns the filter on
  or off for <em>this comparison only</em>.
  </p>
</note>

</section>



<section id="file-case-filter">
<title>Case insensitive filenames</title>

<p>
Files are compared across directories according to their name. This
comparison is case sensitive by default; that is, the files
<file>README</file>, <file>readme</file> and <file>ReadMe</file> would
all be seen as different files.
</p>

<p>
When comparing folders on some filesystems (e.g., HFS+ or FAT) you may
wish to make <app>Meld</app> treat filenames as case insensitive. You
can do this by using the <gui style="button">File Filters</gui> button
on the toolbar and selecting <gui style="menuitem">Ignore Filename Case</gui>.
</p>
</section>



</page>
