NAME

       dirvish-locate - locate file versions in dirvish images

SYNOPSIS

       dirvish-locate vault[:branch] pattern

DESCRIPTION

       Locate versions of files in a dirvish vault

       The index of each image specified vault is searched for paths matching pattern.  Each path found matching
       the  pattern  will be reported followed by a modification time of each version of the file and all images
       having a link to it.

       The optional branch specification will restrict searching to the specified branch.

       Images with an error status will be skipped as will any without index  files.   The  index  file  may  be
       compressed by gzip or bzip2.  See tree and index in dirvish.conf(5) for details.

       The pattern is a perl regular expression to match the final component of the path.  Append .*  to the end
       of  the  pattern  if  you  wish  to  match any substring of the whole path or $ if you wish to anchor the
       pattern to the end of the path.  See perlre(1) for details.

       Directories are excluded from matching as they would wind up matching  every  file  within  them  anyway.
       Symlinks are also excluded from matching.

       If the pattern matches too many paths dirvish-locate will only report the paths matched and not versions.
       As  a  sanity  check if the number of matches is really excessive dirvish-locate will limit the number of
       images searched.  Excessive matches is an indication of an  insufficiently  specific  pattern.   Use  the
       resulting path list to compose a more specific one.

EXIT CODES

       To  facilitate  further  automation  and  integration  of  dirvish-locate with other tools dirvish-locate
       provides rationalised exit codes.  The exit codes are range based.  While the code for a  specific  error
       may  change  from  one  version  to another it will remain within the specified range.  So don't test for
       specific exit codes but instead test for a range of values.  To the degree possible higher  value  ranges
       indicate more severe errors.

       0      success 200-219 An error was encountered in loading a configuration file.

       220-254
              An error was detected in the configuration.

       255    Incorrect usage.

FILES

       /etc/dirvish/master.conf
              alternate master configuration file.

       /etc/dirvish.conf
              master configuration file.

       bank/vault/image/summary
              image creation summary.

       bank/vault/image/index

       bank/vault/image/index.gz

       bank/vault/image/index.bz2
              dirvish index file.

SEE ALSO

       dirvish.conf(5)

BUGS

                                                                                               DIRVISH-LOCATE(1)