Configuration overview

Environment variables
Recoll main configuration file, recoll.conf
The fields file
The mimemap file
The mimeconf file
The mimeview file
The ptrans file
Examples of configuration adjustments

Most of the parameters specific to the recoll GUI are set through the Preferences menu and stored in the standard Qt place ($HOME/.config/Recoll.org/recoll.conf). You probably do not want to edit this by hand.

Recoll indexing options are set inside text configuration files located in a configuration directory. There can be several such directories, each of which defines the parameters for one index.

The configuration files can be edited by hand or through the Index configuration dialog (Preferences menu). The GUI tool will try to respect your formatting and comments as much as possible, so it is quite possible to use both approaches on the same configuration.

The most accurate documentation for the configuration parameters is given by comments inside the default files, and we will just give a general overview here.

For each index, there are at least two sets of configuration files. System-wide configuration files are kept in a directory named like /usr/share/recoll/examples, and define default values, shared by all indexes. For each index, a parallel set of files defines the customized parameters.

The default location of the customized configuration is the .recoll directory in your home. Most people will only use this directory.

This location can be changed, or others can be added with the RECOLL_CONFDIR environment variable or the -c option parameter to recoll and recollindex.

In addition (as of Recoll version 1.19.7), it is possible to specify two additional configuration directories which will be stacked before and after the user configuration directory. These are defined by the RECOLL_CONFTOP and RECOLL_CONFMID environment variables. Values from configuration files inside the top directory will override user ones, values from configuration files inside the middle directory will override system ones and be overriden by user ones. These two variables may be of use to applications which augment Recoll functionality, and need to add configuration data without disturbing the user's files. Please note that the two, currently single, values will probably be interpreted as colon-separated lists in the future: do not use colon characters inside the directory paths.

If the .recoll directory does not exist when recoll or recollindex are started, it will be created with a set of empty configuration files. recoll will give you a chance to edit the configuration file before starting indexing. recollindex will proceed immediately. To avoid mistakes, the automatic directory creation will only occur for the default location, not if -c or RECOLL_CONFDIR were used (in the latter cases, you will have to create the directory).

All configuration files share the same format. For example, a short extract of the main configuration file might look as follows:

        # Space-separated list of files and directories to index.
        topdirs =  ~/docs /usr/share/doc

        [~/somedirectory-with-utf8-txt-files]
        defaultcharset = utf-8

There are three kinds of lines:

  • Comment (starts with #) or empty.

  • Parameter affectation (name = value).

  • Section definition ([somedirname]).

Long lines can be broken by ending each incomplete part with a backslash (\).

Depending on the type of configuration file, section definitions either separate groups of parameters or allow redefining some parameters for a directory sub-tree. They stay in effect until another section definition, or the end of file, is encountered. Some of the parameters used for indexing are looked up hierarchically from the current directory location upwards. Not all parameters can be meaningfully redefined, this is specified for each in the next section.

When found at the beginning of a file path, the tilde character (~) is expanded to the name of the user's home directory, as a shell would do.

Some parameters are lists of strings. White space is used for separation. List elements with embedded spaces can be quoted using double-quotes. Double quotes inside these elements can be escaped with a backslash.

No value inside a configuration file can contain a newline character. Long lines can be continued by escaping the physical newline with backslash, even inside quoted strings.

        astringlist =  "some string \
        with spaces"
        thesame = "some string with spaces"

Parameters which are not part of string lists can't be quoted, and leading and trailing space characters are stripped before the value is used.

Encoding issues. Most of the configuration parameters are plain ASCII. Two particular sets of values may cause encoding issues:

  • File path parameters may contain non-ascii characters and should use the exact same byte values as found in the file system directory. Usually, this means that the configuration file should use the system default locale encoding.

  • The unac_except_trans parameter should be encoded in UTF-8. If your system locale is not UTF-8, and you need to also specify non-ascii file paths, this poses a difficulty because common text editors cannot handle multiple encodings in a single file. In this relatively unlikely case, you can edit the configuration file as two separate text files with appropriate encodings, and concatenate them to create the complete configuration.

Prev Up Next
 Home