The only difference between single-file searching and multi-file searching is that to perform a multi-file search, you must specify the files to be searched. TextWrangler gives you a great deal of flexibility in how to do this. You can search all the files in a given folder, in open editing windows, or in an existing search results browser. For even great control, you can choose a diverse sets of search sources, or apply TextWrangler's advanced multi-criteria file filtering options.
Multi-File Search Results
When you perform a multi-file search, TextWrangler displays every occurrence of the search string in the set of files searched using a search results browser.
The items at the top of the window tells you how many matches TextWrangler found in the set of files you specified, as well as specifying whether there were any error conditions or warnings generated during the search. You can display or hide any combination of errors, warnings, and matches, by checking the appropriate options.
The middle panel lists each line that contains the matched text. (Depending on how you have configured TextWrangler, this list may be a Finder-style hierarchical list, where each match in a file is listed under the file's name, or a flat list where each occurrence is simply displayed in order.) Every match is identified by file name and line number.
To see the contents of a file, click a line in the list of matched searches. The part of the file that contains the search string appears in the lower pane. You cannot edit text in a search results browser. To edit a file, double-click the line that contains the match you want to edit, and the specified file will open at the point of the associated match.
After you have opened a file, you can use the Find Again, Replace, Replace All, and Replace & Find Again commands in the Search menu to continue searching it, as if you had chosen a File by File search. See the next section for information on File by File searching.
Note
You can use a search results window as the basis of another multi-file search. See "Specifying the Search Set" below.
Specifying the Search Set
When you turn on the Multi-File Search option, the Sources drawer of the Find & Replace dialog will open. You can also open or close the Sources drawer at any time by clicking the drawer toggle control at the lower left of the dialog. Use this drawer to specify which files and folders TextWrangler should examine when performing a multi-file search.
You can choose multiple sources for a multi-file search, and you can mix different types of sources. Available sources include:
-
open text documents
-
the files in any selected or recently-searched folder
-
the files listed in a search results browser
-
any saved search targets (listed under "My Files & Folders")
To add a file, folder, or other suitable item to the Sources drawer, click Other in the Find & Replace dialog, and choose the item using the resulting selection sheet. (You can select multiple items to be added.)
To designate any item in the drawer as a search source, click on the box next to its name, or double-click on the name, to add a checkmark. To deselect a search source, click the box next to its name, or double-click its name, to turn off the checkmark. TextWrangler will display a summary of the selected sources in the search items box of the dialog. Here are some common scenarios.
Searching the files in a folder
To search the files in a folder, click on the box next to the folder's name, or double-click its name, in the Sources drawer. If the folder you want to search is not in the Sources drawer, click the Other button at the right of the dialog and pick the folder using the resulting selection sheet.
You can also drag a folder from the Finder directly into the search items box of the Find & Replace dialog to choose it as the source.
Searching all open documents
You can choose any or all open text documents as search sources. This option allows you to search documents that have not yet been saved to a file, or which contain unsaved changes. To choose all open documents, click the box next to the Open Documents item, or double-click on the item, in the Sources drawer.
Searching the files contained in a results browser
If a previous multi-file search found many files that contain your search string, you may want to narrow the search. To search the files listed in any results browser window, click the box next to that browser's name, or double-click on its name, in the Sources drawer. You can also click the box next to the Results Browsers item, or double-click on this item, to search the files listed in all results browsers.
Note
The Choose a Folder dialog will display any packages it encounters as folders (rather than just as single files, the way they appear in the Finder). This allows you to navigate their internal structure just as you would any other folder. Similarly, you can drag a package from the Finder into the path box in the Find & Replace dialog and it will be treated as a true folder rather than as a single file.
Multi-File Search Options
Click the Options button to display the search options sheet.
To search the contents of all subfolders within the folders you choose, select the Search Nested Folders option in the resulting sheet. You can also choose to skip any folders whose names are enclosed in parentheses here by selecting the Skip (...) Folders option, or whether to search the contents of invisible folders by selecting the Search Invisible Folders option.
You can also choose to search only text files or to search all file types. If you have image files or other non-text files in search source folders, it may be a good idea to restrict the search to only text files. This setting is applied in addition to any file filter (see next section) and in fact takes effect before the filter.
To find only files whose contents do not contain the search string, select the Exclude Matches option.
You can further restrict which files from the chosen sources will be searched by applying a file filter. See File Filters. (below) for more details.
File Filters
If you do not want to search every file in the set you selected, but want to include only those that meet certain criteria (such as those created on a certain date, or only those created by TextWrangler and not some other program, or those that are Perl documents), you can use a file filter. Mark the Use File Filter checkbox in the search options sheet and then choose the desired file filter from the Filters pop-up menu. If none of the filters you have already defined meets your needs, you can define a new one, or create a temporary filter.
New Filter
To define a new saved file filter, select New Filter from the pop-up menu. TextWrangler will ask you for a filter name; then the Edit File Filter dialog, below, appears. You can also define new file filters in the File Filters preferences panel.
Note
If you have the Preferences window open, you will not be able to add filters in the Find & Replace dialog. To work around this, close the Preferences window before using the Find & Replace dialog to add new filters.
The Edit File Filter dialog lets you specify multiple criteria that determine whether a given file is selected by the filter. You can choose whether these criteria are exclusive (that is, whether a file must meet every listed test to be selected) or inclusive (that is, whether a file that meets any of the tests is selected) using the Every (AND) and Any (OR) radio buttons at the top of the dialog.
To add a test, click More Criteria. A new row appears in the dialog, as shown below.
The leftmost column lets you specify which attribute of a file you wish to test. TextWrangler lets you test a file's name, the name of its enclosing folder, its creator or type, its creation and modification date (or both date and time), or its Finder label, visibility, or the programming or markup language it is written in. You can also test the content of a file, using the "Contents" criterion.
The middle column lets you choose the test to be applied to the selected attribute. The available options here change depending on what attribute you selected. If you choose Visibility in the first column, for instance, your only choices are whether the file is or is not visible, However, if you choose File Name in the first column, the middle column lets you test to see if the name does or does not exactly match, contain, begin with, or end with a particular string. You can also test file names to see if they match wildcard or Grep patterns.
Note
In wildcard patterns, the asterisk (*) and question mark (?) characters have special meanings. The asterisk matches any number of characters, such that "*.c" matches any file whose name ends with ".c". The question mark matches a single character, so that "foo?" matches "food", fool", "foot", and many other words. Both the asterisk and the question mark can be used anywhere in a wildcard pattern, and any number of either can be used in a single pattern.
Grep patterns, also known as regular expressions, are a powerful method of selecting file names based on classes of text or repeating text. They are covered in great detail in the next chapter.
The right column specifies the match criterion. For example, when filtering by File Name, you type the text you want the name to match, contain, begin with, or end with (or not). When filtering by Language, you choose a supported language from a pop-up menu.
Tip
To quickly set a match criterion, drag a file from the Finder to a field in the Define File Filter dialog. TextWrangler inserts the appropriate attribute from the dragged file, if possible.
Specifying Time and Date Criteria
When using a time or date criterion, you can use the special words below to specify dates and times relative to the current date and time.
|
Word
|
Means...
|
|
now
|
current date and time
|
|
today
|
midnight on the current date
|
|
yesterday
|
current date and time minus 24 hours
|
|
tomorrow
|
current date and time plus 24 hours
|
You can add any number of criteria using the More Criteria button. To delete the last criterion, click the Fewer Criteria button. To select any single criterion for deletion, press the Option key and click on the desired item. To select multiple continuous criteria, press Option-Shift and drag across the items, or to select discontinuous criteria, press Command-Option and click on the desired items.
Click Save to save the file filter and use it for this search. TextWrangler will ask you to name the filter, and it will then appear in the Filters pop-up menu in the Find & Replace dialog (and in the Define File Filter dialog). Click Revert to undo any changes you have made to the filter. (Hold the Option key when you click Revert to skip the confirmation alert.)
Filtering by Name
In order to provide the greatest possible flexibility, TextWrangler offers several different criteria for filtering based on file names
File Name: Tests the complete string corresponding to the file name.
File Name Root: Tests only the "root" portion of the file name. Given a name of the form "foo.txt", the root is the string which occurs before the period, in this case "foo".
File Name Suffix: Tests only the file name suffix. In the above example, the suffix is "txt". Note that the suffix does not include the period.
Temporary Filters
Choose "(current criteria)" from the pop-up menu in the Find & Replace dialog to reuse the last set of criteria applied (either from using a saved filter, or from using the Edit button to define criteria). Thus, you can use filter criteria on the fly, without the need to create and store a throwaway filter.
Editing and Deleting Filters
To edit a file filter you have already defined, choose it from the Filters pop-up menu, change it as desired, and click Save. Since each filter must have a unique name, saving it will replace the old version of the filter. To delete a filter entirely, visit the File Filters panel in the Preferences window. (You can also create or modify filters there.)
