---
name: "dirvish-locate"
section: "1"
platform: "linux"
package: "dirvish"
version: "1.2.1-2.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/dirvish-locate"
---

# dirvish-locate(1)

locate file versions in dirvish images

## 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)](/dirvish.conf/5.md)** 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)](/perlre/1.md)** 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