Path translations

In some cases, the document paths stored inside the index do not match the actual ones, so that document previews and accesses will fail. This can occur in a number of circumstances:

  • When using multiple indexes it is a relatively common occurrence that some will actually reside on a remote volume, for example mounted via NFS. In this case, the paths used to access the documents on the local machine are not necessarily the same than the ones used while indexing on the remote machine. For example, /home/me may have been used as a topdirs elements while indexing, but the directory might be mounted as /net/server/home/me on the local machine.

  • The case may also occur with removable disks. It is perfectly possible to configure an index to live with the documents on the removable disk, but it may happen that the disk is not mounted at the same place so that the documents paths from the index are invalid.

  • As a last example, one could imagine that a big directory has been moved, but that it is currently inconvenient to run the indexer.

Recoll has a facility for rewriting access paths when extracting the data from the index. The translations can be defined for the main index and for any additional query index.

The path translation facility will be useful whenever the documents paths seen by the indexer are not the same as the ones which should be used at query time.

In the above NFS example, Recoll could be instructed to rewrite any file:///home/me URL from the index to file:///net/server/home/me, allowing accesses from the client.

The translations are defined in the ptrans configuration file, which can be edited by hand or from the GUI external indexes configuration dialog: PreferencesExternal index dialog, then click the Paths translations button on the right below the index list.


Due to a current bug, the GUI must be restarted after changing the ptrans values (even when they were changed from the GUI).