summaryrefslogtreecommitdiff
path: root/gsearchtool/help/C/index.docbook
blob: 99ab888fbffaf1e7eec4d7e789044f888a7d1afb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "2.26">
  <!ENTITY manrevision "2.8">
  <!ENTITY date "March 2009">
  <!ENTITY app "Search for Files">
  <!ENTITY ug "MATE Desktop User Guide">
]>
<!-- 
      (Do not remove this comment block.)
  Maintained by the MATE Documentation Project
  http://developer.mate.org/projects/gdp 
  Template version: 2.0 beta
  Template last modified Jan 25, 2005  
-->
<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title>&app; Manual</title>

    <abstract role="description">
      <para>
    	A search tool to find files, folders and documents on your computer.
      </para>
    </abstract>

    <copyright> 
      <year>2005</year> 
      <holder>Dennis Cranston</holder> 
    </copyright>
    <copyright> 
      <year>2002</year> 
      <year>2003</year> 
      <year>2004</year> 
      <holder>Sun Microsystems</holder> 
    </copyright> 
    <copyright> 
      <year>2000</year> 
      <holder>Alexander Kirillov</holder> 
    </copyright>
<!-- translators: uncomment this:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->
    <publisher> 
      <publishername> MATE Documentation Project </publishername> 
    </publisher> 

   &legal;

    <authorgroup> 
      <author role="maintainer"> 
	<firstname>Dennis</firstname> 
	<surname>Cranston</surname> 
	<affiliation> 
	  <orgname>&app; Maintainer</orgname> 
	  <address>dennis_cranston@yahoo.com</address> 
	</affiliation> 
      </author> 
      <author> 
	<firstname>Sun</firstname> 
	<surname>MATE Documentation Team</surname> 
	<affiliation> 
	  <orgname>Sun Microsystems</orgname> 
	  <address></address> 
	</affiliation> 
      </author> 
      <author> 
	<firstname>Alexander</firstname> 
	<surname>Kirillov</surname> 
	<affiliation> 
	  <orgname>MATE Documentation Project</orgname> 
	  <address> <email>kirillov@math.sunysb.edu</email> </address> 
	</affiliation> 
      </author> 
<!-- This is appropriate place for other contributors: translators,
      maintainers,  etc. Commented out by default.
       <othercredit role="translator">
	<firstname>Latin</firstname> 
	<surname>Translator 1</surname> 
	<affiliation> 
	  <orgname>Latin Translation Team</orgname> 
	  <address> <email>translator@gnome.org</email> </address> 
	</affiliation>
	<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>

 <revhistory>
 <!-- <revision> 
	<revnumber>&app; Manual V&manrevision;</revnumber> 
	<date>&date;</date> 
	<revdescription> 
	  <para role="author">Sun GNOME Documentation Team</para>
	  <para role="publisher">MATE Documentation Project</para>
	</revdescription> 
 </revision>
-->
   <revision> 
			<revnumber>&app; Manual V2.7</revnumber> 
			<date>June 2005</date> 
			<revdescription> 
	  		<para role="author">Joachim Noreiko
				<email>jnoreiko@yahoo.com</email>
			</para>
	  		<para role="publisher">&app; Maintainer</para>
			</revdescription> 
  </revision>
  <revision> 
			<revnumber>&app; Manual V2.6</revnumber> 
			<date>January 2005</date> 
			<revdescription> 
	  		<para role="author">Dennis Cranston
				<email>dennis_cranston@yahoo.com</email>
			</para>
	  		<para role="publisher">&app; Maintainer</para>
			</revdescription> 
 </revision>
 <revision> 
			<revnumber>&app; Manual V2.4</revnumber> 
			<date>February 2004</date> 
			<revdescription> 
	  		<para role="author">Sun GNOME Documentation Team</para>
	  		<para role="publisher">MATE Documentation Project</para>
			</revdescription> 
 </revision>
 <revision> 
			<revnumber>&app; Manual V2.3</revnumber> 
			<date>September 2002</date> 
			<revdescription> 
	  		<para role="author">Sun GNOME Documentation Team</para>
	  		<para role="publisher">MATE Documentation Project</para>
			</revdescription> 
 </revision>
 <revision> 
			<revnumber>&app;l Manual V2.2</revnumber> 
			<date>August 2002</date> 
			<revdescription> 
	  		<para role="author">Sun GNOME Documentation Team</para>
	  		<para role="publisher">MATE Documentation Project</para>
			</revdescription> 
 </revision> 
 <revision> 
			<revnumber>&app; Manual V2.1</revnumber> 
			<date>July 2002</date> 
			<revdescription> 
	  		<para role="author">Sun GNOME Documentation Team</para>
	  		<para role="publisher">MATE Documentation Project</para>
			</revdescription> 
 </revision> 
 <revision> 
			<revnumber>&app; Manual V2.0</revnumber> 
			<date>May 2002</date> 
			<revdescription> 
	  		<para role="author">Sun GNOME Documentation Team</para>
	  		<para role="publisher">MATE Documentation Project</para>
			</revdescription> 
 </revision> 
 <revision> 
	<revnumber>&app; Manual</revnumber> 
	<date>2000</date> 
	<revdescription> 
	  <para role="author">Alexander Kirillov
	    <email>kirillov@math.sunysb.edu</email>
	  </para>
	  <para role="publisher">MATE Documentation Project</para>
	</revdescription> 
 </revision> 
 </revhistory> 

    <releaseinfo>This manual describes version &appversion; of &app;.
    </releaseinfo> 
  </articleinfo> 

  <indexterm> 
    <primary>Search Tool</primary> 
  </indexterm> 

<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->

  <sect1 id="gsearchtool-introduction"> 
    <title>Introduction</title> 
    <para>The <application>&app;</application> application enables you to search for files on your system. To perform a basic search, you can type a filename or a partial filename, with or without wildcards. To refine your search, you can apply additional search options.</para>
    <para><application>&app;</application> uses the <command>find</command>, <command>grep</command>, and <command>locate</command> UNIX commands.  By default, when performing a basic search <application>&app;</application> first uses the <command>locate</command> command, and then uses the slower but more thorough <command>find</command> command.</para>
    <para>The case sensitivity of the search depends on your operating system. For example, on Linux, the <command>find</command>, <command>grep</command>, and <command>locate</command> commands support the <literal>-i</literal> option, so all searches are case-insensitive.</para>
  </sect1>

  <sect1 id="gsearchtool-getting-started">
    <title>Getting Started</title> 

    <para>You can start <application>&app;</application> in the following ways:
    </para> 
    <variablelist>
    	<varlistentry>
    		<term>From a <guimenu>Menu Bar</guimenu> on a panel</term>
    		<listitem>
    		<para>Choose <menuchoice><guisubmenu>Places</guisubmenu><guimenuitem>Search for Files...</guimenuitem></menuchoice></para>
    		</listitem>
    	</varlistentry>
   	<varlistentry>
    		<term>From a <guimenu>Main Menu</guimenu> on a panel</term>
    		<listitem>
    		<para>Choose <menuchoice><guimenuitem>Search for Files...</guimenuitem></menuchoice></para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>From a command line</term>
    		<listitem>
    		<para>Execute the following command: <command>mate-search-tool</command></para>
    		<para> 		 
    		</para> 
    		</listitem>
    	</varlistentry>
    </variablelist>

    <para>When you start <application>&app;</application>, the following window is displayed.</para>

    <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig"> 
	<title>&app; Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/mate-search-tool_window.png" format="PNG"/> 
	    </imageobject>
	    <textobject> 
	      <phrase>Shows &app; main window. </phrase> 
	    </textobject> 
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

  </sect1>

<!-- ================ Usage ================================ -->

  <sect1 id="gsearchtool-usage"> 
    <title>Usage</title>

    <sect2 id="gsearchtool-simple">
    <title>To Perform a Basic Search</title>
    
    <para>To perform a basic search for a file on the system, perform the following steps:</para>
    <orderedlist>
    <listitem><para>Enter the search text in the <guilabel>Name contains</guilabel> field. The search text can be a filename or partial filename, with or without wildcards, as shown in the following table:</para>

      <informaltable frame="all">
        <tgroup cols="3" colsep="1" rowsep="1">
          <colspec colname="COLSPEC0" colwidth="33*"/>
          <colspec colname="COLSPEC1" colwidth="33*"/>
          <colspec colname="COLSPEC2" colwidth="34*"/>
          <thead>
            <row valign="top">
              <entry colname="COLSPEC0">
                <para>Name Contains Text</para></entry>
              <entry colname="COLSPEC1">
                <para>Example</para></entry>
              <entry colname="COLSPEC2">
                <para>Result</para></entry>
            </row>
          </thead>
          <tbody>
            <row valign="top">
              <entry>
                <para>Full or partial filename
                </para>
              </entry>
              <entry>
                <para><userinput>myfile.txt</userinput>
                </para>
              </entry>
              <entry>
                <para><application>&app;</application> searches for all files that contain the text <userinput>myfile.txt</userinput> in the filename.
                </para>
              </entry>
            </row>
            <row valign="top">
              <entry>
                <para>Partial filename combined with wildcards (*, [, ])
                </para>
              </entry>
              <entry>
                <para><userinput>*.[ch]</userinput>
                </para>
              </entry>
              <entry>
                <para><application>&app;</application> searches for all files that have extension <userinput>.c</userinput> or <userinput>.h</userinput>.
                </para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </informaltable>
    </listitem>
    <listitem><para>In the <guilabel>Look in folder</guilabel> field, select the folder or device from which you want <application>&app;</application> to begin the search. 
</para></listitem>
    <listitem><para>Click <guibutton>Find</guibutton> to perform the search. </para>
    </listitem>
    </orderedlist>
    <para>
      <application>&app;</application> searches in the directory that you specify and the subdirectories of the directory.
<application>&app;</application> displays the results of the search in the <guilabel>Search results</guilabel> list box. If <application>&app;</application> does not find any files that match the search criteria, the application displays the message "No files found" in the <guilabel>Search results</guilabel> list box. 
</para>
    <para>By default, <application>&app;</application> will perform a quick search using the <command>locate</command> command followed by a more thorough second search using the <command>find</command> command. The <command>locate</command> command is faster because it uses a database of information about files. If this database is more than a week old, <application>&app;</application> could warn you that the search results may be out of date and give you the option of disabling the quick search. To update the database, run the command <command>updatedb</command> as the root user.</para>
  </sect2>
    
    <sect2 id="gsearchtool-advanced">
    <title>To Add Search Options</title>
    <para>You can add additional options to search for a file on the system. To add search options, perform the following steps:</para>
  	<orderedlist>
    		<listitem><para>Click on the <guilabel>Select more options</guilabel> text. </para></listitem>
    		<listitem><para>Click on the <guilabel>Available options</guilabel> drop-down list.</para></listitem>
    		<listitem><para>Select the search option that you want to apply.</para></listitem>
    		<listitem><para>Click <guibutton>Add</guibutton>. </para></listitem>
    		<listitem><para>Specify the required search information for the search option, as described in <xref linkend="tbl-search-rules"/>.</para></listitem>
    		<listitem><para>Repeat the above steps for each search option that you want to apply.</para></listitem>
    	</orderedlist>	
    	<para>To remove a search option from the current search, click on the <guibutton>Remove</guibutton> button next to the option. </para>
    	<para>To disable the search options from the current search, click on the <guilabel>Select more options</guilabel> text.</para>
    
    <table id="tbl-search-rules" frame="topbot">
    <title>Search Options</title> 
		  <tgroup cols="2" colsep="1" rowsep="1">
			 <colspec colname="COLSPEC0" colwidth="33*"/>
			 <colspec colname="COLSPEC1" colwidth="33*"/>
			 <thead> 
				<row valign="top"> 
				  <entry> 
					 <para>Option Name</para></entry> 
				  <entry> 
					 <para>Description</para></entry> 
				</row> 
			 </thead> 
			 <tbody> 
				<row valign="top"> 
				  <entry> 
					 <para>Contains the text</para></entry> 
				  <entry> 
					 <para>Search for files of type plain text that contain the specified text.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Date modified less than</para></entry> 
				  <entry> 
					 <para>Search for files that are modified less than the period specified in days.</para></entry>  
				</row>
				<row valign="top"> 
				  <entry> 
					 <para>Date modified more than</para></entry> 
				  <entry> 
					 <para>Search for files that are modified longer than the period specified in days.</para></entry>  
				</row>
				<row valign="top"> 
				  <entry> 
					 <para>Size at least</para></entry> 
				  <entry> 
					 <para>Search for files that are equal to or larger than the size specified in kilobytes.</para></entry>  
				</row>
				<row valign="top"> 
				  <entry> 
					 <para>Size at most</para></entry> 
				  <entry> 
					 <para>Search for files that are smaller than or equal to the size specified in kilobytes.</para></entry>  
				</row>
				<row valign="top"> 
				  <entry> 
					 <para>File is empty</para></entry> 
				  <entry> 
					 <para>Search for empty files.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Owned by user</para></entry> 
				  <entry> 
					 <para>Search for files that are owned by the user specified. Type the name of the user in the text box provided.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Owned by group</para></entry> 
				  <entry> 
					 <para>Search for files that are owned by the group specified. Type the name of the group in the text box provided. </para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Owner is unrecognized</para></entry> 
				  <entry> 
					 <para>Search for files that are owned by a user or group that is unknown to the system.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Name does not contain</para></entry> 
				  <entry> 
					 <para>Search for filenames that do not contain the string that you enter. Enter a full filename or a partial filename with wildcards in the field provided. Use * to indicate a sequence of characters. Use ? to indicate a single character. The search is case sensitive.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Name matches regular expression</para></entry> 
				  <entry> 
					 <para>Search for files that contain the specified regular expression in their directory path or filename. Type the regular expression in the text box provided. </para></entry>  
				</row>
				<row valign="top"> 
				  <entry> 
					 <para>Show hidden and backup files</para></entry> 
				  <entry> 
					 <para>Include hidden and backup files in the search. </para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Follow symbolic links</para></entry> 
				  <entry> 
					 <para>Follow symbolic links when searching for files.</para></entry>  
				</row> 
				<row valign="top"> 
				  <entry> 
					 <para>Exclude other filesystems</para></entry> 
				  <entry> 
					 <para>Search in directories that are in the same filesystem as the start directory.</para></entry>  
				</row> 
				 				
			 </tbody> 
		  </tgroup> 
		</table> 
    
    </sect2>

    <sect2 id="gsearchtool-stop">
    <title>To Stop a Search</title>
    <para>Click <guibutton>Stop</guibutton> to stop a search before <application>&app;</application> completes the search. </para>
    </sect2>
    
    <sect2 id="gsearchtool-view">
    <title>To Open a Displayed File</title>
    <para>To open a file displayed in the <guilabel>Search results</guilabel> list box, perform one of the following steps:</para>
    <itemizedlist>
    <listitem><para>Right-click on the file, then choose <guimenuitem>Open</guimenuitem>. </para></listitem>
     <listitem><para>Double-click on the file. </para></listitem>
    </itemizedlist>
    <para>To open the folder that contains a file displayed in the <guilabel>Search results</guilabel> list box, right-click on the file, then choose <guimenuitem>Open Containing Folder</guimenuitem>.</para>
    </sect2>

    <sect2 id="gsearchtool-delete">
    <title>To Delete a Displayed File</title>
    <para>To delete a file displayed in the <guilabel>Search results</guilabel> list box, right-click on the file, then choose <guimenuitem>Move to Trash</guimenuitem>. </para>
    </sect2>
    
    <!--
    <sect2 id="gsearchtool-search-command">
    <title>To View the Search Command Used by &app;</title>
    <para>To view the command that <application>&app;</application> used to perform the previous search, choose <menuchoice><guimenu>Search</guimenu><guimenuitem>Show Command</guimenuitem></menuchoice>. The <guilabel>Search Command Line</guilabel> displays the command. </para>
    </sect2>
    -->
    
    <sect2 id="gsearchtool-savetofile">
    <title>To Save the Search Results</title>
    <para>To save the results of the last search that <application>&app;</application> performed, right-click in the <guilabel>Search results</guilabel> list, then choose <guimenuitem>Save Results As</guimenuitem>. Enter the name of the file to which you want to save the results, then click Save.</para>
    </sect2>
 
  </sect1>

<!-- ============= Settings ============================== -->

  <sect1 id="gsearchtool-settings-gsettings-keys">
    <title>Settings</title> 

    <para><application>&app;</application> provides gsettings keys to modify some of its behavior.  The gsettings values can be changed by starting the <application>Configuration Editor</application> in the following ways:
    </para> 
    <variablelist>
    	<varlistentry>
    		<term><guimenu>Applications</guimenu> menu</term>
    		<listitem>
    		<para>Choose <menuchoice><guisubmenu>System Tools</guisubmenu><guimenuitem>dconf Editor</guimenuitem></menuchoice>. </para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>Execute the following command: <command>dconf-editor</command></para> 
    		</listitem>
    	</varlistentry>	
    </variablelist>
    
    <sect2 id="gsearchtool-disablequicksearch">
    <title>Disable Quick Search</title>
    <para>Key name: org.mate.search-tool.disable-quick-search</para>
    <para>Default value: false</para>
    <para><application>&app;</application> speeds up file name searches by using the <command>locate</command> command.  <command>Locate</command> provides a secure way to index and quickly search for file names.  Because <command>locate</command> relies on a file index, the <guilabel>Search results</guilabel> list may not always be up to date.</para>
    </sect2>

    <sect2 id="gsearchtool-disablesecondscan">
    <title>Disable Quick Search Second Scan</title>
    <para>Key name: org.mate.search-tool.disable-quick-search-second-scan</para>
    <para>Default value: false</para>
    <para>After completing a quick search, <application>&app;</application> will perform a thorough search using the <command>find</command> command.  The purpose of this second scan is to find files that have not been indexed.  Files that match the search criteria are added to the <guilabel>Search results</guilabel> list keeping the list up to date.</para>
    </sect2>

    <sect2 id="gsearchtool-quicksearchexclude">
    <title>Quick Search Excluded Paths</title>
    <para>Key name: org.mate.search-tool.quick-search-excluded-paths</para>
    <para>Default values: [/mnt/*,/media/*,/dev/*,/tmp/*,/proc/*,/var/*]</para>
    <para><application>&app;</application> will not perform a quick search for paths defined by this key.  File name searches in the defined paths will use the <command>find</command> command.  The wildcards '*' and '?' are supported.</para>
    </sect2>

    <sect2 id="gsearchtool-secondscanexclude">
    <title>Quick Search Second Scan Excluded Paths</title>
    <para>Key name: org.mate.search-tool.quick-search-second-scan-excluded-paths</para>
    <para>Default values: [/]</para>
    <para><application>&app;</application> will not perform a second scan after a quick search for the paths defined by this key.  Quick searches in the defined paths will not be followed by a thorough search using the <command>find</command> command.  The wildcards '*' and '?' are supported.</para>
    </sect2>

    <sect2 id="gsearchtool-showoptions">
    <title>Show Additional Options</title>
    <para>Key name: org.mate.search-tool.show-additional-options</para>
    <para>Default value: false</para>
    <para>This key determines if the <guilabel>Select more options</guilabel> section is expanded when <application>&app;</application> is started.</para>
    </sect2>
    
  </sect1>

</article>