<type>documentation</type>
<domain>intro</domain>
<id>tutorial-search</id>
<title>Tutorial: Search in Files</title>
<date>$Date$</date>
<product>per+</product>

The `Search in Files <script:show_panel#panel_type="batch-search">`__ tool in Wing Pro and
Wing Personal supports multi-file batch search of the disk, project, open editors,
documentation, or other sets of files. It can also search and replace using wildcards and
regular expressions.

.. image:: search-in-files.png
  :width: 782
  :height: 596

Before worrying about the details, try a simple batch search on the ``example1.py`` file.
Select ``Current File`` from the ``Look in`` selector on the ``Search in Files`` tool.
Then enter ``PrintAs`` into the search area.

Wing will start searching immediately, restarting the search whenever you alter the search
string or make other changes that affect the result set, or if the files being searched
change. 

When you are done typing, you should see results similar to those shown in the screen shot
above. Click on the first result line to display ``example1.py`` in the editor with the
corresponding search match highlighted.

Next, change the ``Look in`` selector to ``Project Files`` and change your search string
to ``HTML``. This works the same way as searching a single file, but lists the results for
all files that have been added to your project.

You can also search all currently open files or within Wing's documentation by instead
selecting ``Open Files`` or ``Documentation`` from ``Look in``.

**File Filters**

In many cases, searching is more useful if constrained to a subset of files in your
projects such as only Python files. This can be done with by selecting ``Python Files`` in
the ``Filter`` selector. You can also define your own file filters using the ``Create/Edit
Filters`` item in the ``Filter`` selector. This will display the `Files > File Types >
File Filters <script:show_preferences_gui#prefname="main.file-filters">`__ preference:

.. image:: file-filters.png
  :width: 604
  :height: 134

Each file filter has a name and a list of include and exclude specifications. Each of
these specifications can be applied to the file name, directory name, or the file's MIME
type. An example would be to specify ``*.js`` wildcard for matching Javascript files by
name, or using the ``text/html`` mime type for all HTML files.

**Searching Disk**

Wing can also search directly on disk. Try this by typing a directory path in the ``Look
in`` area. Assuming you haven't changed the search string, this should search for ``HTML``
in all text files in that directory.

Disk search can be recursive, in which case Wing searches all sub-directories as well.
This is done by selecting a directory in the ``Look in`` scope selector and enabling
``Recursive Directory Search`` in the ``Options`` menu.

You can alter the format of the result list with the ``Show Line Numbers`` item and
``Result File Name`` group in the ``Options`` menu.

Note that searching ``Project Files`` is usually faster than searching a directory
structure because the set of files is precomputed and thus the search only needs to look
in the files and not spend time discovering them.

**Multi-file Replace**

When replacing within multiple files, Wing opens each changed file into an editor, whether
or not it is already open. This allows you to undo changes by not saving files or by
issuing ``Undo`` within each editor.

If you check ``Replace Operates on Disk`` in the ``Options`` menu, Wing will change files
directly on disk instead of opening editors into the IDE. This can be much faster but is
not recommended unless you are using a revision control system that can be used to
undo mistakes.

Note that even when operating directly on disk, Wing will replace changes in already-open
editors only within the IDE. This avoids creating two versions of a file if there are
already edits in the IDE's copy. We recommend selecting ``Save All`` from the file menu
immediately after each replace operation. This avoids losing parts of a global replace
operation.

See `Multi-File Search and Replace <ref:edit/search-in-files>`__ for details.
