Settings, configuration overview

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).

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 with a plain text editor 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.

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 (the values in these files are often commented out, and just present to indicate the default coded in the program). For each index, a parallel set of files defines the customized parameters.

On Unix-like systems, the default location of the customized configuration is the .recoll directory in your home. On Windows it is C:/Users/[you]/AppData/Local/Recoll. Most people will only use this directory.

The default location for the 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.

In addition, 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:

  • Comment lines start with a hash mark #.

  • Parameter assignment: name = value.

  • Section definitions: [somedirname].

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.

Important

Global parameters must not be defined in a directory subsection, else they will not be found at all by the Recoll code, which looks for them at the top level (e.g. skippedPaths).

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.

Important

Quotes processing is ONLY applied to parameter values which are lists. Double quoting a single value like, e.g. dbdir will result in an incorrect value, with quotes included. This is quite confusing, and may have been a design mistake but it is much too late to fix.

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 (meaning unaccenting exception translations) should be encoded in UTF-8. If your system locale is not UTF-8 (which is now very rare), 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.