## GNOME Search Tool Manual

2000
Alexander Kirillov

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation License from the Free Software Foundation by visiting their Web site or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

## Introduction

GNOME Search Tool is a utility for searching files on your system. It can perform many types of search: by filename, by modification date, by file contents, etc. It is included in the `gnome-utils` package, which is a part of the GNOME desktop environment. This document describes version 1.2 of GNOME Search Tool.

The search tool can be started by selecting GNOME Search Tool from Utilities submenu of the Main Menu, or by running the command `gsearchtool` on the command line.

Note that GNOME Search Tool is just a front-end to the UNIX commands `find`, `grep`, and `locate`. These commands are extremely powerful, but not very easy for a new user. GNOME Search Tool provides an easy-to-use interface for most common uses of these commands. If you need to perform some type of search which is not covered by the GNOME Search Tool, chances are that you can do it from the command line, using `find` and `grep` with appropriate options. In this case, you should read the info pages for these commands, which can be done using the GNOME Help Browser.

## Usage

GNOME Search Tool provides two types of search: Full find and Quick find. Full find is reliable and provides many possibilities, but can be slow. Quick find uses special technique for speeding up search; it is much faster, but can only search by filename, and is not as accurate as full find. This section describes full find mode; quick find is described in .

### Main search window

Main search window

To start a search, you must give the GNOME Search Tool the search criteria and the directory to start in.

By default, the search starts in the current working directory; if the GNOME Search Tool was started from the menu, then the current working directory is your home directory. You can change the starting directory by entering any valid path in the Start in directory field, or by choosing a directory using the Browse... button. For example, to search through all the files in on your system, enter `/` in this field (warning: it will take very long time).

By default, GNOME Search Tool also searches through all subdirectories of the given directory; you can turn this behavior off by enabling the option Don't search subdirectories. For finer control, you can enable the option Don't search mounted filesystems, which will exclude from the search subdirectories which are physically located (mounted) on drives or partitions other than the starting directory — see for details.

The only search criterion presented by default is the Filename. You can use the wildcards * (matches any sequence of symbols, including an empty one) and ? (matches any single symbol) in this field. For example, to find the files with the extension `txt`, enter `*.txt` in this field; to find all the files that start with the letter D, enter `D*` (warning: file names are case-sensitive!). You can also specify much more complicated search criteria — see .

After you have specified the search criteria and starting directory, press Start. This will take some time (depending on the directory size and system speed), after which you will be presented with a window containing the list of all the files matching your criteria (it may be empty), as shown in . If the search is taking too much time, you can abort it by pressing Stop button.

### Search results window

Search results window

In the search results window, you can double-click on any file to open it. It will have the same effect as double-clicking on this file in a File Manager window — that is, the file will be opened using the default action for this file type. You can also save the list of found files to disk by pressing Save button. You will be prompted for a filename to save the list to; the list will be saved in a plain text format.

## Search Criteria

In addition to the simple filename search described above, the GNOME Search Tool allows you to specify other criteria. To do so, you should select the appropriate criteria type from the drop-down list (located to the left of the Add button), and press Add. This will add this criterion to the already existing ones. GNOME Search Tool will search for files meeting all of the specified criteria. For example, shows search for all files with extension `txt` which were modified during the last 7 days and which contain the word GNOME.

### Sample GNOME Search Session

Sample GNOME Search Session

You can remove any of the criteria you had previously added by pressing Remove button next to it. You can also temporarily disable a criterion by unchecking the Enable check-button next to it.

Below is the list of all possible criteria types:

- Filename — search by filename. As usual, you can use the wildcards * and ? in the search. Remember also that UNIX file names are case-sensitive.

- Don't search subdirectories — if this option is selected, GNOME Search Tool will not search the files in the subdirectories of the start directory.

- File owner — search by the name of the user owning the file.

- File owner group — search by the name of the group owning the file.

- Last modification time — search for files which were modified during the last N days (to be precise, during the last N*24 hours).

- Don't search mounted filesystems — if this option is selected, GNOME Search Tool will only search in the subdirectories which are mounted on the same device (disk) as the starting directory. For example, if the starting directory is `/` and is mounted on `/dev/hda` (first hard drive), and it has a subdirectory `/home` which is mounted on `/dev/hdb` (second hard drive), then `/home` will not be searched. This option can be useful to exclude files on the removable media (CD-ROM, floppy) from the search.

- Empty file — this criterion matches the empty file. Mostly used by system administrators for system maintenance.

- Invalid user or group — matches files whose owner or group is not known to the system. This option can be useful when searching for files belonging to users who have been removed from the system. Mostly used by system administrators for system maintenance.

- Filenames except — matches all files except those whose filename is given. As before, you can use wildcards. For example, if you specify in this field `*~`, GNOME Search Tool will exclude from the search all files with names ending with tilde (~).

- Simple substring search — matches all files that contain given substring. Since this option involves reading contents of every file, it can slow down the search significantly. Note: you can't use wildcards with this option.

- Regular expression search — matches all files that contain given regular expression. Since this option involves reading contents of every file, it can slow down the search significantly.

- Extended regular expression search — matches all files that contain given extended regular expression. Since this option involves reading contents of every file, it can slow down the search significantly.

For those unfamiliar with the notion of regular expression, let us just say that this is an extremely flexible and powerful syntax for pattern matching. Unlike simple wildcard matching, it allows logical operations (and, or, not), lists of symbols to match, checking for a string in the beginning of the line, and much more. Detailed description of regular expressions and extended regular expressions can be found in the man page for grep. New users will probably find it too complicated to use, but for more experienced users, regular expressions can be very useful.

## Quick find mode

This section describes quick find mode of GNOME search tool. To use this mode, switch to Quick find (locate) window, shown in .

### Quick find window

Quick find window

In the quick search mode, GNOME Search tool doesn not actually search for a file on the disk — instead, it uses a special database containing the names of all the files on the system. It makes search much faster. However, it also means that the only type of search you can do is by filename. Moreover, this search will not find files which were added after the last database update (on most systems, it is updated daily, usually at night — see below for more info).

To find a file using the quick search mode, just enter a substring of the file name in the Locate file field. For example, to find all the files whose filenames contain the string searchtool, enter `searchtool` in this field. This will also show all the files that contain the string searchtool in their full pathname — in particular, all the files in `/usr/share/help/gsearchtool`.

To restrict search to a subdirectory, you can use the directory name in combination with the wildcards. For example, to do quick search for all files with extension `txt` in the directory `/home/user`, enter `/home/user/*.txt` in the Locate file field.

The quick search mode is actually a front-end to `locate` command, so if you need more detailed information, read the appropriate manual page.

### The locate database

This section discusses updating the database used for quick search. Unless you are a system administrator or just curious, you do not need to read it.

On most systems, the database used for `locate` command (and thus, for quick search mode of GNOME Search tool), is updated daily, usually at nights. This is done as a `cron` job — see the manual page for `cron` if you are unfamiliar with this utility. Note that if your computer is usually turned off at night time, the database doesn't get updated. In this case, you should change the default update time by either manully editing `/etc/crontab` or using a graphical tool such as cromagnon. This requires system administrator (root) privileges.

You can also issue the command Update database now by running the command `updatedb`. Again, this requires system administrator (root) privileges. Without any options, it rebuilds the whole database, for all the files on your system. It also has many command line options allowing you to fine-tune it (for example, istructing it to skip certain directories). For more information, read the manual page for `updatedb`.

## Authors

GNOME Search Tool was written by George Lebl (jirka@5z.com). Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. (Instructions for submitting bug reports can be found on-line.) If you are using GNOME 1.1 or later, you can also use Bug Report Tool (`bug-buddy`), available in the Utilities submenu of Main Menu, for submitting bug reports.

This manual was written by Alexander Kirillov (kirillov@math.sunysb.edu). Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs@gnome.org. You can also add your comments online by using the GNOME Documentation Status Table.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        59 Temple Place - Suite 330
        Boston, MA 02111-1307
        USA