Recoll user manual

Configuration

For reference, the GUI settings are stored in $HOME/.config/Recoll.org/recoll.conf on Unix-like systems and C:/Users/[you]/AppData/Roaming/Recoll/recoll.ini on Windows.

The parameters for each Recoll index 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.

There is a default index configuration directory, used when not specified otherwise. On Unix-like systems it is located in $HOME/.recoll. Under Windows, it is located in C:\Users\[you]\AppData\Local\Recoll.

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

For each index, there are actually at least two sets of configuration files. The parameters set in the locations listed above override or complement system-wide configuration files which come with the installation and are kept in a directory named like /usr/share/recoll/examples on Unix-like systems (or an equivalent on other systems), and define default values, shared by all indexes (the values in these files are often commented out, and just present to indicate the default coded in the program).

The local configuration directory only stores additional or overriding parameters. The defaults are stored in the central location. You should never edit the central files as they will be overwritten by a software update.

The location for the index configuration directory can be changed, or others can be added for separate indexes with the RECOLL_CONFDIR environment variable or the -c option parameter to recoll and recollindex.

Special use: in addition, for each index, 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 overridden 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 default configuration directory does not exist when either recoll or recollindex is 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 which case, 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:

Lines which are empty or only containing white space are ignored.

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. The same convention is used on Windows.

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: