Provided by: glimpse_4.18.7-3build1_amd64 bug

NAME

       glimpse - search quickly through entire file systems

OVERVIEW

       Glimpse  (which  stands  for  GLobal  IMPlicit SEarch) is a very popular UNIX indexing and
       query system that allows you to search through a large set of files very quickly.  Glimpse
       supports  most  of  agrep's  options  (agrep  is  our  powerful version of grep) including
       approximate matching (e.g., finding misspelled words),  Boolean  queries,  and  even  some
       limited  forms  of regular expressions.  It is used in the same way, except that you don't
       have to specify file names.  So, if you are looking for a needle  anywhere  in  your  file
       system,  all  you  have  to  do is say glimpse needle and all lines containing needle will
       appear preceded by the file name.

       To use glimpse you first need  to  index  your  files  with  glimpseindex.   For  example,
       glimpseindex  -o  ~   will  index  everything  at  or  below your home directory.  See man
       glimpseindex for more details.

       Glimpse is also available for web sites, as a set of tools called  WebGlimpse.   (The  old
       glimpseHTTP  is  no  longer supported and is not recommended.)  See http://webglimpse.net/
       for more information.

       Glimpse includes all of agrep and can be used instead of agrep by giving a file name(s) at
       the  end  of  the  command.   This will cause glimpse to ignore the index and run agrep as
       usual.  For example, glimpse -1 pattern file is the same as agrep -1 pattern file.   Agrep
       is distributed as a self-contained package within glimpse, and can be used separately.  We
       added a new option to agrep:  -r searches recursively the directory and  everything  below
       it (see agrep options below); it is used only when glimpse reverts to agrep.

       Mail  majordomo@webglimpse.net  with  SUBSCRIBE  wgusers  in  the  body to be added to the
       Webglimpse users mailing list.  This is now the location where glimpse questions are  also
       discussed.   Bugs can be reported at http://webglimpse.net/bugzilla/ HTML version of these
       manual pages can be found in  http://webglimpse.net/docs/glimpsehelp.html  Also,  see  the
       glimpse home pages in http://webglimpse.net/glimpse

SYNOPSIS

       glimpse - [almost all letters] pattern

INTRODUCTION

       We  start with simple ways to use glimpse and describe all the options in detail later on.
       Once an index is built, using glimpseindex, searching for pattern is as easy as saying

       glimpse pattern

       The output of glimpse is similar to that of agrep (or any other grep).  The pattern can be
       any agrep legal pattern including a regular expression or a Boolean query (e.g., searching
       for Tucson AND Arizona is done by glimpse 'Tucson;Arizona').

       The speed of glimpse depends mainly on the number and sizes of the files  that  contain  a
       match  and only to a second degree on the total size of all indexed files.  If the pattern
       is reasonably uncommon, then all matches will be reported in a few  seconds  even  if  the
       indexed  files total 500MB or more.  Some information on how glimpse works and a reference
       to a detailed article are given below.

       Most of agrep (and other grep's) options are supported,  including  approximate  matching.
       For example,

       glimpse -1 'Tuson;Arezona'

       will  output  all lines containing both patterns allowing one spelling error in any of the
       patterns (either insertion, deletion, or substitution), which in this case  is  definitely
       needed.

       glimpse -w -i 'parent'

       specifies  case  insensitive  (-i)  and  match  on  complete  words (-w).  So 'Parent' and
       'PARENT' will match, 'parent/child' will match, but 'parenthesis' or  'parents'  will  not
       match.   (Starting  at  version 3.0, glimpse can be much faster when these two options are
       specified, especially for very large indexes.  You may want to set an alias especially for
       "glimpse -w -i".)

       The -F option provides a pattern that must match the file name.  For example,

       glimpse -F '\.c$' needle

       will  find  the  pattern needle in all files whose name ends with .c.  (Glimpse will first
       check its index to determine which files may contain the pattern and then run agrep on the
       file names to further limit the search.)  The -F option should not be put at the end after
       the main pattern (e.g., "glimpse needle -F hay" is incorrect).

A Detailed Description of All the Options of Glimpse

       -#     # is an integer between 1 and 8 specifying the maximum number of  errors  permitted
              in  finding  the  approximate  matches  (the  default  is  zero).   Generally, each
              insertion, deletion, or substitution counts as one error.  It is possible to adjust
              the  relative  cost  of  insertions,  deletions and substitutions (see -I -D and -S
              options).   Since  the  index  stores  only  lower  case  characters,   errors   of
              substituting  upper case with lower case may be missed (see LIMITATIONS).  Allowing
              errors in the match requires more time and can slow down the match by a  factor  of
              2-4.  Be very careful when specifying more than one error, as the number of matches
              tend to grow very quickly.

       -a     prints attribute names.  This option applies only to Harvest SOIF  structured  data
              (used   with  glimpseindex  -s).   (See  http://harvest.sourceforge.net/  for  more
              information about the Harvest project.)

       -A     used for glimpse internals.

       -b     prints the byte offset (from the beginning of the file) of the end of  each  match.
              The first character in a file has offset 0.

       -B     Best  match  mode.   (Warning: -B sometimes misses matches.  It is safer to specify
              the number of errors explicitly.)  When -B is specified and no  exact  matches  are
              found,  glimpse  will  continue to search until the closest matches (i.e., the ones
              with minimum number of errors) are found, at which point the following message will
              be  shown:  "the  best  match  contains x errors, there are y matches, output them?
              (y/n)" This message refers to the number of matches found in the index.  There  may
              be  many  more  matches  in  the actual text (or there may be none if -F is used to
              filter files).  When the -#, -c, or -l options are  specified,  the  -B  option  is
              ignored.   In  general,  -B may be slower than -#, but not by very much.  Since the
              index stores only lower case characters, errors of  substituting  upper  case  with
              lower case may be missed (see LIMITATIONS).

       -c     Display  only  the  count  of  matching  records.   Only  files  with count > 0 are
              displayed.

       -C     tells glimpse to send its queries to glimpseserver.

       -d 'delim'
              Define delim to be the separator between two records.  The default  value  is  '$',
              namely  a  record  is  by  default a line.  delim can be a string of size at most 8
              (with possible use of ^ and $), but not a regular  expression.   Text  between  two
              delim's,  before  the  first  delim,  and after the last delim is considered as one
              record.  For example, -d '$$' defines paragraphs as records and -d '^From ' defines
              mail  messages  as  records.   glimpse matches each record separately.  This option
              does not currently work with regular expressions.   The  -d  option  is  especially
              useful  for  Boolean  AND queries, because the patterns need not appear in the same
              line  but  in  the  same  record.   For  example,  glimpse  -F  mail  -d   '^From '
              'glimpse;arizona;announcement'  will  output  all mail messages (in their entirety)
              that have the 3 patterns anywhere in the message (or  the  header),  assuming  that
              files  with  'mail'  in their name contain mail messages.  If you want the scope of
              the record to be the whole file, use the -W  option.   Glimpse  warning:  Use  this
              option with care.  If the delimiter is set to match mail messages, for example, and
              glimpse finds the pattern in a regular file, it may not find the delimiter and will
              therefore  output  the whole file.  (The -t option - see below - can be used to put
              the delim at the end of the record.)  Performance Note: Agrep (and glimpse) resorts
              to  more  complex  search  when  the  -d  option is used.  The search is slower and
              unfortunately no more than 32 characters can be used in the pattern.

       -Dk    Set the cost of a deletion to k (k is a positive integer).  This  option  does  not
              currently work with regular expressions.

       -e pattern
              Same as a simple pattern argument, but useful when the pattern begins with a `-'.

       -E     prints  the  lines  in  the  index  (as  they  appear in the index) which match the
              pattern.  Used mostly for debugging and maintenance of the index.  This is  not  an
              option that a user needs to know about.

       -f file_name
              this  option  has  a different meaning for agrep than for glimpse: In glimpse, only
              the files whose names are listed in file_name are matched.  (The file names have to
              appear as in .glimpse_filenames.)  In agrep, the file_name contains the list of the
              patterns that are searched.  (Starting at version 3.6, this option for  glimpse  is
              much faster for large files.)

       -F file_pattern
              limits  the  search  to  those  files whose name (including the whole path) matches
              file_pattern.  This option can be used in a  variety  of  applications  to  provide
              limited search even for one large index.  If file_pattern matches a directory, then
              all files with this directory on their path  will  be  considered.   To  limit  the
              search  to actual file names, use $ at the end of the pattern.  file_pattern can be
              a regular expression and even a Boolean pattern.  This  option  is  implemented  by
              running  agrep  file_pattern  on  the  list  of file names obtained from the index.
              Therefore, searching the index itself takes the same amount of time,  but  limiting
              the  second  phase  of  the  search  to  only  a  few files can speed up the search
              significantly.  For example,

              glimpse -F 'src#\.c$' needle

              will search for needle in all .c files with src somewhere along the path.   The  -F
              file_pattern  must appear before the search pattern (e.g., glimpse needle -F '\.c$'
              will not work).  It is possible to use some of agrep's options when  matching  file
              names.   In  this case all options as well as the file_pattern should be in quotes.
              (-B and -v do not work very well as part of a file_pattern.)  For example,

              glimpse -F '-1 \.html' pattern

              will allow one spelling error when matching .html to the file names (so ".htm"  and
              ".shtml" will match as well).

              glimpse -F '-v \.c$' counter

              will search for 'counter' in all files except for .c files.

       -g     prints  the  file  number (its position in the .glimpse_filenames file) rather than
              its name.

       -G     Output the (whole) files that contain a match.

       -h     Do not display filenames.

       -H directory_name
              searches for the index and the other .glimpse files in directory_name.  The default
              is  the  home  directory.  This option is useful, for example, if several different
              indexes are maintained for different archives (e.g., one for mail messages, one for
              source code, one for articles).

       -i     Case-insensitive  search  — e.g., "A" and "a" are considered equivalent.  Glimpse's
              index stores all patterns in lower case (see LIMITATIONS below).  Performance Note:
              When -i is used together with the -w option, the search may become much faster.  It
              is recommended to have -i and -w as defaults, for example, through  an  alias.   We
              use the following alias in our .cshrc file
              alias glwi 'glimpse -w -i'

       -Ik    Set  the cost of an insertion to k (k is a positive integer).  This option does not
              currently work with regular expressions.

       -j     If the index was constructed with the -t option, then -j will output the files last
              modification  dates in addition to everything else.  There are no major performance
              penalties for this option.

       -J host_name
              used in conjunction with glimpseserver (-C) to connect to one particular server.

       -k     No symbol in the pattern is treated as a meta character.  For example,  glimpse  -k
              'a(b|c)*d'  will  find  the occurrences of a(b|c)*d whereas glimpse 'a(b|c)*d' will
              find substrings that match the regular expression 'a(b|c)*d'.  (The only  exception
              is  ^  at  the  beginning of the pattern and $ at the end of the pattern, which are
              still interpreted in the usual way.  Use \^ or \$ if you need them verbatim.)

       -K port_number
              used in conjunction with glimpseserver (-C) to connect to one particular server  at
              the specified TCP port number.

       -l     Output  only the files names that contain a match.  This option differs from the -N
              option in that the files themselves are searched, but the matching  lines  are  not
              shown.

       -L x | x:y | x:y:z
              if  one  number  is  given,  it is a limit on the total number of matches.  Glimpse
              outputs only the first x matches.  If  -l  is  used  (i.e.,  only  file  names  are
              sought),  then  the limit is on the number of files; otherwise, the limit is on the
              number of records.  If two numbers are given (x:y), then y is an added limit on the
              total  number  of  files.   If  three numbers are given (x:y:z), then z is an added
              limit on the number of matches per file.  If any of the x, y, or z is set to 0,  it
              means  to  ignore  it  (in other words 0 = infinity in this case);  for example, -L
              0:10 will output all matches to the first 10 files  that  contain  a  match.   This
              option  is particularly useful for servers that needs to limit the amount of output
              provided to clients.

       -m     used for glimpse internals.

       -M     used for glimpse internals.

       -n     Each matching record (line) is prefixed by its record (line) number  in  the  file.
              Performance  Note: To compute the record/line number, agrep needs to search for all
              record delimiters (or line breaks), which can slow down the search.

       -N     searches only the index (so the search is faster).  If -o or -b are used  then  the
              result  is  the number of files that have a potential match plus a prompt to ask if
              you want to see the file names.  (If -y is used, then there is no  prompt  and  the
              names  of  the  files will be shown.)  This could be a way to get the matching file
              names without even having access to the files themselves.   However,  because  only
              the  index  is  searched, some potential matches may not be real matches.  In other
              words, with -N you will not miss any  file  but  you  may  get  extra  files.   For
              example,  since  the  index stores everything in lower case, a case-sensitive query
              may match a file that has only a case-insensitive match.  Boolean queries may match
              a  file that has all the keywords but not in the same line (indexing with -b allows
              glimpse to figure out whether the keywords are close, but it cannot figure out from
              the  index  whether they are exactly on the same line or in the same record without
              looking at the file).  If the index was not build with -o or -b, then  this  option
              outputs the number of blocks matching the pattern.  This is useful as an indication
              of how long the search will take.  All files are partitioned into  usually  200-250
              blocks.   The  file  .glimpse_statistics  contains  the  total number of blocks (or
              glimpse -N a will give a pretty good estimate; only blocks with no  occurrences  of
              'a' will be missed).

       -o     the  opposite  of -t: the delimiter is not output at the tail, but at the beginning
              of the matched record.

       -O     the file names are not printed before every matched record; instead, each  filename
              is printed just once, and all the matched records within it are printed after it.

       -p     (from  version  4.0B1  only)  Supports reading compressed set of filenames.  The -p
              option allows you to utilize compressed  `neighborhoods'  (sets  of  filenames)  to
              limit  your  search, without uncompressing them.  Added mostly for WebGlimpse.  The
              usage is:
              "-p filename:X:Y:Z" where "filename" is the file with compressed  neighborhoods,  X
              is  an  offset  into that file (usually 0, must be a multiple of sizeof(int)), Y is
              the length glimpse must access from that file (if 0, then whole  file;  must  be  a
              multiple  of  sizeof(int)),  and  Z must be 2 (it indicates that "filename" has the
              sparse-set representation of compressed neighborhoods: the  other  values  are  for
              internal  use  only).  Note  that any colon ":" in filename must be escaped using a
              backslash .

       -P     used for glimpse internals.

       -q     prints the offsets of the beginning and end of each matched record.  The difference
              between -q and -b is that -b prints the offsets of the actual matched string, while
              -q prints the offsets of the whole record where the  match  occurred.   The  output
              format is @x{y}, where x is the beginning offset and y is the end offset.

       -Q     when  used  together with -N glimpse not only displays the filename where the match
              occurs, but the exact occurrences (offsets) as seen in the index.  This  option  is
              relevant  only  if  the  index  was  built with -b;  otherwise, the offsets are not
              available in the index.  This option is ignored when used not with -N.

       -r     This option is an agrep option and it will be ignored in glimpse, unless glimpse is
              used  with a file name at the end which makes it run as agrep.  If the file name is
              a directory name, the -r option will search (recursively) the whole  directory  and
              everything below it.  (The glimpse index will not be used.)

       -R k   defines  the  maximum size (in bytes) of a record.  The maximum value (which is the
              default) is 48K.  Defining the maximum to be lower than the deafult  may  speed  up
              some searches.

       -s     Work  silently, that is, display nothing except error messages.  This is useful for
              checking the error status.

       -Sk    Set the cost of a substitution to k (k is a positive integer).   This  option  does
              not currently work with regular expressions.

       -t     Similar to the -d option, except that the delimiter is assumed to appear at the end
              of the record.  Glimpse will output the record starting from the end  of  delim  to
              (and including) the next delim.  (See warning for the -d option.)

       -T directory
              Use  directory  as a place where temporary files are built.  (Glimpse produces some
              small temporary files usually in /tmp.)   This  option  is  useful  mainly  in  the
              context  of  structured  queries for the Harvest project, where the temporary files
              may be non-trivial, and the /tmp directory may not have enough space for them.

       -U     (starting at version 4.0B1) Interprets an index created  with  the  -X  or  the  -U
              option  in glimpseindex.  Useful mostly for WebGlimpse or similar web applications.
              When glimpse outputs matches, it will display the filename, the URL, and the  title
              automatically.

       -v     (This  option  is an agrep option and it will be ignored in glimpse, unless glimpse
              is used with a file name at the end which makes  it  run  as  agrep.)   Output  all
              records/lines  that  do  not  contain  a  match.  (Glimpse does not support the NOT
              operator yet.)

       -V     prints the current version of glimpse.

       -w     Search for the pattern as a word — i.e., surrounded by non-alphanumeric characters.
              For  example, glimpse -w car will match car, but not characters and not car10.  The
              non-alphanumeric must surround the match;  they cannot be counted as errors.   This
              option  does  not work with regular expressions.  Performance Note: When -w is used
              together with the -i option, the search may become much faster.  The  -w  will  not
              work  with  $,  ^,  and _ (see BUGS below).  It is recommended to have -i and -w as
              defaults, for example, through an alias.  We use the following alias in our  .cshrc
              file
              alias glwi 'glimpse -w -i'

       -W     The  default for Boolean AND queries is that they cover one record (the default for
              a record is one line) at a time.  For example, glimpse 'good;bad' will  output  all
              lines  containing  both  'good'  and  'bad'.   The  -W  option changes the scope of
              Booleans to be the whole file.  Within a file glimpse will output  all  matches  to
              any  of  the  patterns.  So, glimpse -W 'good;bad' will output all lines containing
              'good' or 'bad', but only in files that contain both patterns.   The  NOT  operator
              '~'  can  be  used  only  with  -W.   It is described later on.  The OR operator is
              essentially unaffected  (unless  it  is  in  combination  with  the  other  Boolean
              operations).   For  structured  queries, the scope is always the whole attribute or
              file.

       -x     The pattern must match the whole line.  (This option is translated to -w  when  the
              index  is  searched and it is used only when the actual text is searched.  It is of
              limited use in glimpse.)

       -X     (from version 4.0B1 only) Output the names of files that contain a  match  even  if
              these  files  have  been  deleted  since  the index was built.  Without this option
              glimpse will simply ignore these files.

       -y     Do not prompt.  Proceed with the match as  if  the  answer  to  any  prompt  is  y.
              Servers (or any other scripts) using glimpse will probably want to use this option.

       -Y k   If the index was constructed with the -t option, then -Y x will output only matches
              to files that were created or modified within the last x days.  There are no  major
              performance penalties for this option.

       -z     Allow  customizable  filtering,  using  the  file  .glimpse_filters  to perform the
              programs listed there for each match.  The best example is compress/decompress.  If
              .glimpse_filters include the line
              *.Z   uncompress <
              (separated  by  tabs)  then before indexing any file that matches the pattern "*.Z"
              (same syntax as the one for .glimpse_exclude) the command listed is executed  first
              (assuming  input  is  from  stdin,  which is why uncompress needs <) and its output
              (assuming it goes to stdout) is indexed.  The file itself is not changed (i.e.,  it
              stays  compressed).   Then if glimpse -z is used, the same program is used on these
              files on the fly.  Any program can be used (we run 'exec').  For example,  one  can
              filter  out parts of files that should not be indexed.  Glimpseindex tries to apply
              all filters in .glimpse_filters in the order they are given.  For example,  if  you
              want  to  uncompress  a  file and then extract some part of it, put the compression
              command (the example  above)  first  and  then  another  line  that  specifies  the
              extraction.  Note that this can slow down the search because the filters need to be
              run before files are searched.  (See also glimpseindex.)

       -Z     No op.  (It's useful for glimpse's internals. Trust us.)

       The characters `$', `^', `', `[', `]', `^',  `|',  `(',  `)',  `!',  and  `\'  can  cause
       unexpected  results  when included in the pattern, as these characters are also meaningful
       to the shell.  To avoid these problems, enclose the entire pattern in single quotes, i.e.,
       'pattern'.  Do not use double quotes (").

PATTERNS

       glimpse  supports  a  large  variety  of  patterns, including simple strings, strings with
       classes of  characters,  sets  of  strings,  wild  cards,  and  regular  expressions  (see
       LIMITATIONS).

       Strings
              Strings  are  any  sequence  of  characters,  including the special symbols `^' for
              beginning of line and `$' for end of line.  The following special characters ( `$',
              `^',  `',  `[',  `^',  `|', `(', `)', `!', and `\' ) as well as the following meta
              characters special to glimpse (and agrep): `;', `,', `#', `<', `>', `-',  and  `.',
              should  be  preceded  by  `\' if they are to be matched as regular characters.  For
              example, \^abc\\ corresponds to the string ^abc\, whereas ^abc corresponds  to  the
              string abc at the beginning of a line.

       Classes of characters
              a  list  of  characters  inside [] (in order) corresponds to any character from the
              list.  For example, [a-ho-z] is any character between a and h or between o  and  z.
              The  symbol  `^'  inside  []  complements the list.  For example, [^i-n] denote any
              character in the character set except character 'i' to 'n'.  The  symbol  `^'  thus
              has  two  meanings, but this is consistent with egrep.  The symbol `.' (don't care)
              stands for any symbol (except for the newline symbol).

       Boolean operations
              Glimpse supports an `AND' operation denoted by the symbol  `;'  an  `OR'  operation
              denoted  by  the  symbol  `,',  a limited version of a 'NOT' operation (starting at
              version 4.0B1) denoted by the symbol `~', or any combination.  For example, glimpse
              'pizza;cheeseburger'  will  output  all lines containing both patterns.  glimpse -F
              'gnu;\.c$' 'define;DEFAULT' will output all  lines  containing  both  'define'  and
              'DEFAULT'  (anywhere  in  the  line,  not necessarily in order) in files whose name
              contains 'gnu' and ends with .c.  glimpse '{political,computer};science' will match
              'political  science'  or  'science  of  computers'.   The  NOT operation works only
              together with the -W option and it is generally applies  only  to  the  whole  file
              rather to individual records.  Its output may sometimes seem counterintuitive.  Use
              with care.  glimpse -W 'fame;~glory' will output all lines containing 'fame' in all
              files  that  contain 'fame' but do not contain 'glory'; This is the most common use
              of NOT, and in this case it works as expected.  glimpse -W '~{fame;glory}' will  be
              limited  to  files  that  do  not  contain  both  words,  and will output all lines
              containing one of them.

       Wild cards
              The symbol '#' is used to  denote  a  sequence  of  any  number  (including  0)  of
              arbitrary characters (see LIMITATIONS).  The symbol # is equivalent to .* in egrep.
              In fact, .* will work too, because it is a valid regular  expression  (see  below),
              but  unless  this  is  part  of  an  actual regular expression, # will work faster.
              (Currently glimpse is experiencing some problems with #.)

       Combination of exact and approximate matching
              Any pattern inside angle brackets <> must match the text exactly even if the  match
              is  with  errors.   For  example, <mathemat>ics matches mathematical with one error
              (replacing the last s with an a), but mathe<matics> does not match mathematical  no
              matter how many errors are allowed.  (This option is buggy at the moment.)

       Regular expressions
              Since the index is word based, a regular expression must match words that appear in
              the index for glimpse to find it.  Glimpse first strips the regular expression from
              all  non-alphabetic characters, and searches the index for all remaining words.  It
              then applies the regular expression matching algorithm to the files  found  in  the
              index.   For  example,  glimpse 'abc.*xyz' will search the index for all files that
              contain both 'abc' and 'xyz', and then search  directly  for  'abc.*xyz'  in  those
              files.  (If you use glimpse -w 'abc.*xyz', then 'abcxyz' will not be found, because
              glimpse will think that abc and xyz need to be matches to whole words.)  The syntax
              of  regular  expressions  in glimpse is in general the same as that for agrep.  The
              union operation `|', Kleene closure `*', and  parentheses  ()  are  all  supported.
              Currently  '+'  is  not  supported.   Regular  expressions are currently limited to
              approximately 30 characters (generally excluding meta  characters).   Some  options
              (-d,  -w,  -t, -x, -D, -I, -S) do not currently work with regular expressions.  The
              maximal number of errors for regular expressions that use '*' or  '|'  is  4.  (See
              LIMITATIONS.)

       structured queries
              Glimpse  supports some form of structured queries using Harvest's SOIF format.  See
              STRUCTURED QUERIES below for details.

EXAMPLES

       (Run "glimpse '^glimpse' this-file" to get a list of all  examples,  some  of  which  were
       given earlier.)

       glimpse -F 'haystack.h$' needle
              finds all needles in all haystack.h's files.

       glimpse -2 -F html Anestesiology
              outputs  all  occurrences  of  Anestesiology  with  two  errors  in files with html
              somewhere in their full name.

       glimpse -l -F '\.c$' variablename
              lists the names of all .c files that contain variablename (the -l option lists file
              names rather than output the matched lines).

       glimpse -F 'mail;1993' 'windsurfing;Arizona'
              finds  all  lines containing windsurfing and Arizona in all files having `mail' and
              '1993' somewhere in their full name.

       glimpse -F mail 't.j@#uk'
              finds all mail addresses (search only files with mail somewhere in their name) from
              the  uk,  where  the  login  name  ends  with  t.j,  where the . stands for any one
              character.  (This is very useful to find a login name of someone whose middle  name
              you don't know.)

       glimpse -F mbox -h -G  . > MBOX
              concatenates all files whose name matches `mbox' into one big one.

SEARCHING IN COMPRESSED FILES

       Glimpse  includes  an  optional new compression program, called cast, which allows glimpse
       (and agrep) to search the compressed files without having to decompress them.  The  search
       is  actually  significantly  faster  when  the files are compressed.  However, we have not
       tested cast as thoroughly as we would have liked, and a mishap in a compression  algorithm
       can  cause  loss of data, so we recommend at this point to use cast very carefully.  We do
       not support or maintain cast.  (Unless you specifically use cast, the default is to ignore
       it.)

GLIMPSEINDEX FILES

       All  files  used by glimpse are located at the directory(ies) where the index(es) is (are)
       stored and have .glimpse_  as  a  prefix.   The  first  two  files  (.glimpse_exclude  and
       .glimpse_include) are optionally supplied by the user.  The other files are built and read
       by glimpse.

       .glimpse_exclude
              contains a list of files that  glimpseindex  is  explicitly  told  to  ignore.   In
              general,  the  syntax  of .glimpse_exclude/include is the same as that of agrep (or
              any other grep).  The lines in the .glimpse_exclude file are matched  to  the  file
              names,  and  if  they  match, the files are excluded.  Notice that agrep matches to
              parts  of  the  string!   e.g.,  agrep  /ftp/pub  will  match   /home/ftp/pub   and
              /ftp/pub/whatever.   So, if you want to exclude /ftp/pub/core, you just list it, as
              is,  in  the  .glimpse_exclude  file.   If   you   put   "/home/ftp/pub/cdrom"   in
              .glimpse_exclude,  every  file  name  that  matches  that  string will be excluded,
              meaning all files below it.  You can use ^ to indicate  the  beginning  of  a  file
              name,  and  $ to indicate the end of one, and you can use * and ? in the usual way.
              For example /ftp/*html  will  exclude  /ftp/pub/foo.html,  but  will  also  exclude
              /home/ftp/pub/html/whatever;  if you want to exclude files that start with /ftp and
              end with html use ^/ftp*html$ Notice that putting a * at the beginning  or  at  the
              end is redundant (in fact, in this case glimpseindex will remove the * when it does
              the indexing).  No other meta characters are  allowed  in  .glimpse_exclude  (e.g.,
              don't  use  .* or # or |).  Lines with * or ? must have no more than 30 characters.
              Notice that, although the index itself will not be indexed, the list of file  names
              (.glimpse_filenames)   will   be   indexed   unless  it  is  explicitly  listed  in
              .glimpse_exclude.

       .glimpse_filters
              See the description above for the -z option.

       .glimpse_include
              contains a list of files that glimpseindex is explicitly told  to  include  in  the
              index  even  though they may look like non-text files.  Symbolic links are followed
              by glimpseindex only if they are specifically included here.  If a file is in  both
              .glimpse_exclude and .glimpse_include it will be excluded.

       .glimpse_filenames
              contains  the  list of all indexed file names, one per line.  This is an ASCII file
              that can also be used with agrep to search for a file name leading to a  fast  find
              command.  For example,
              glimpse 'count#\.c$' ~/.glimpse_filenames
              will  output  the  names  of all (indexed) .c files that have 'count' in their name
              (including anywhere on the path from the index).  Setting the  following  alias  in
              the .login file may be useful:
              alias findfile 'glimpse -h :1 ~/.glimpse_filenames'

       .glimpse_index
              contains  the  index.   The  index  consists  of  lines,  each starting with a word
              followed by a list of block numbers (unless the -o or -b options are used, in which
              case each word is followed by an offset into the file .glimpse_partitions where all
              pointers are kept).  The block/file numbers are stored in binary form, so  this  is
              not an ASCII file.

       .glimpse_messages
              contains the output of the -w option (see above).

       .glimpse_partitions
              contains  the  partition  of  the  indexed space into blocks and, when the index is
              built with the -o or -b options, some  part  of  the  index.   This  file  is  used
              internally by glimpse and it is a non-ASCII file.

       .glimpse_statistics
              contains  some  statistics about the makeup of the index.  Useful for some advanced
              applications and customization of glimpse.

       .glimpse_turbo
              An added data structure (used under glimpseindex -o or -b only) that helps to speed
              up queries significantly for large indexes.  Its size is 0.25MB.  Glimpse will work
              without it if needed.

STRUCTURED QUERIES

       Glimpse can search for Boolean  combinations  of  "attribute=value"  terms  by  using  the
       Harvest  SOIF parser library (in glimpse/libtemplate).  To search this way, the index must
       be made by using the -s option of glimpseindex (this can be used in conjunction with other
       glimpseindex  options). For glimpse and glimpseindex to recognize "structured" files, they
       must be in SOIF format. In this format, each value is prefixed by an  attribute-name  with
       the  size  of  the  value (in bytes) present in "{}" after the name of the attribute.  For
       example, The following lines are part of an SOIF file:
       type{17}:       Directory-Listing
       md5{32}:        3858c73d68616df0ed58a44d306b12ba
       Any string can serve as an attribute name.  Glimpse "pattern;type=Directory-Listing"  will
       search  for "pattern" only in files whose type is "Directory-Listing".  The file itself is
       considered to be one "object" and its name/url appears as the first attribute with an  "@"
       prefix; e.g., @FILE { http://xxx... } The scope of Boolean operations changes from records
       (lines) to whole files when structured queries are used in glimpse (since individual query
       terms  can look at different attributes and they may not be "covered" by the record/line).
       Note that glimpse can only search for patterns in the value parts of the SOIF file:  there
       are  some  attributes (like the TTL, MD5, etc.) that are interpreted by Harvest's internal
       routines.  See RFC 2655 for more detailed information of the SOIF format.

REFERENCES

       1.     U. Manber and S. Wu, "GLIMPSE: A Tool  to  Search  Through  Entire  File  Systems,"
              Usenix  Winter 1994 Technical Conference (best paper award), San Francisco (January
              1994), pp. 23-32.  Also, Technical Report #TR 93-34,  Dept.  of  Computer  Science,
              University  of  Arizona,  October 1993 (a postscript file is available by anonymous
              ftp at ftp://webglimpse.net/pub/glimpse/TR93-34.ps).

       2.     S. Wu and U. Manber, "Fast Text Searching Allowing Errors," Communications  of  the
              ACM 35 (October 1992), pp. 83-91.

SEE ALSO

       agrep(1), ed(1), ex(1), glimpseindex(1), glimpseserver(1), grep(1), sh(1), csh(1).

LIMITATIONS

       The  index of glimpse is word based.  A pattern that contains more than one word cannot be
       found in the index.  The way glimpse overcomes this weakness is by  splitting  any  multi-
       word pattern into its set of words and looking for all of them in the index.  For example,
       glimpse 'linear programming' will first consult the index to  find  all  files  containing
       both  linear  and programming, and then apply agrep to find the combined pattern.  This is
       usually an effective solution, but it can be slow for cases  where  both  words  are  very
       common, but their combination is not.

       As  was  mentioned  in  the  section  on  PATTERNS  above,  some  characters serve as meta
       characters for glimpse and need to be preceded by '\' to search for them.  The most common
       examples  are  the  characters  '.'  (which  stands  for a wild card), and '*' (the Kleene
       closure).  So, "glimpse ab.de" will match  abcde,  but  "glimpse  ab\.de"  will  not,  and
       "glimpse  ab*de" will not match ab*de, but "glimpse ab\*de" will.  The meta character - is
       translated automatically to a hypen unless it appears between [] (in which case it denotes
       a range of characters).

       The  index  of glimpse stores all patterns in lower case.  When glimpse searches the index
       it first converts all patterns to lower  case,  finds  the  appropriate  files,  and  then
       searches  the  actual  files using the original patterns.  So, for example, glimpse ABCXYZ
       will first find all files containing abcxyz in any combination of lower and  upper  cases,
       and  then  searches  these  files  directly,  so  only the right cases will be found.  One
       problem with this approach is discovering misspellings that are  caused  by  wrong  cases.
       For  example,  glimpse  -B abcXYZ will first search the index for the best match to abcxyz
       (because the pattern is converted to lower case); it will find that there are matches with
       no errors, and will go to those files to search them directly, this time with the original
       upper cases.  If the closest match is, say AbcXYZ, glimpse may miss it, because it doesn't
       expect  an error.  Another problem is speed.  If you search for "ATT", it will look at the
       index for "att".  Unless you use -w to match the whole word, glimpse may  have  to  search
       all files containing, for example, "Seattle" which has "att" in it.

       There is no size limit for simple patterns and simple patterns within Boolean expressions.
       More  complicated  patterns,  such  as  regular  expressions,  are  currently  limited  to
       approximately  30  characters.  Lines are limited to 1024 characters.  Records are limited
       to 48K, and may be truncated if they are larger than that.  The limit of record length can
       be changed by modifying the parameter Max_record in agrep.h.

       Glimpseindex does not index words of size > 64.

BUGS

       In some rare cases, regular expressions using * or # may not match correctly.

       A  query  that  contains  no alphanumeric characters is not recommended (unless glimpse is
       used as agrep and the file names are provided).  This is an understatement.

       The notion of "match to the whole word" (the -w option)  can  be  tricky  sometimes.   For
       example,  glimpse -w 'word$' will not match 'word' appearing at the end of a line, because
       the extra '$' makes the pattern more than just one simple word.  The same thing can happen
       with  ^  and with _.  To be on the safe side, use the -w option only when the patterns are
       actual words.

       Please send bug reports or comments to gvelez@webglimpse.net.

DIAGNOSTICS

       Exit status is 0 if any matches are found, 1 if none, 2 for syntax errors or  inaccessible
       files.

AUTHORS

       Udi Manber and Burra Gopal, Department of Computer Science, University of Arizona, and Sun
       Wu, the National Chung-Cheng University, Taiwan. Now maintained by Golda Velez at Internet
       WorkShop (Email:  gvelez@webglimpse.net)

                                        November 10, 1997                              GLIMPSE(1)