debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-12-01 23:24:11 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/man1/notmuch-config.rst

274 lines
9.5 KiB
ReStructuredText
Raw Permalink Normal View History

doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
==============
notmuch-config
==============
SYNOPSIS
========
**notmuch** **config** **get** <*section*>.<*item*>
CLI/config: default to storing all config in external files Previously the fact that some configuration options were only stored in the database (and thus editing the config file had no effect) was a source of user confusion. This was fixed with the series ending at d9af0af1646. On the other hand, the underlying partition of config options into those stored by default in the database and those stored in the config file remained. This is also confusing, since now some invocations of "notmuch config set" modify the config file, and others silently modify the database instead. With this commit, it is up to the user to decide which configuration to modify. A new "--database" option is provided for notmuch config to enable modifying the configuration information in the database; otherwise the default is to update an external config file.
2021-02-19 13:41:36 +01:00
**notmuch** **config** **set** [--database] <*section*>.<*item*> [*value* ...]
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
**notmuch** **config** **list**
DESCRIPTION
===========
The **config** command can be used to get or set settings in the notmuch
config: test whether an item is stored in the database by name QUERY_STRING was only used in two places, both to test whether a variable should be stored in (or retrieved from) the database. Since other configuration variables might be stored in the database in the future, consolidate that test into a single function. We also document that these configuration options should not be placed in the config file.
2017-10-21 04:25:42 +02:00
configuration file and corresponding database.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**get**
The value of the specified configuration item is printed to
stdout. If the item has multiple values (it is a list), each value
is separated by a newline character.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**set**
The specified configuration item is set to the given value. To
specify a multiple-value item (a list), provide each value as a
separate command-line argument.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
If no values are provided, the specified configuration item will
be removed from the configuration file.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
CLI/config: default to storing all config in external files Previously the fact that some configuration options were only stored in the database (and thus editing the config file had no effect) was a source of user confusion. This was fixed with the series ending at d9af0af1646. On the other hand, the underlying partition of config options into those stored by default in the database and those stored in the config file remained. This is also confusing, since now some invocations of "notmuch config set" modify the config file, and others silently modify the database instead. With this commit, it is up to the user to decide which configuration to modify. A new "--database" option is provided for notmuch config to enable modifying the configuration information in the database; otherwise the default is to update an external config file.
2021-02-19 13:41:36 +01:00
With the `--database` option, updates configuration metadata
stored in the database, rather than the default (text)
configuration file.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**list**
Every configuration item is printed to stdout, each on a separate
line of the form::
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: clean up manpage description of "notmuch-config list" output The escaping in the description of the output of "notmuch-config list" appears to have been inherited from some previous attempts at documentation. It leaked out in the actual generated manpage documentation, where it looks like this: list Every configuration item is printed to stdout, each on a separate line of the form: *section*.\ *item*\ =\ *value* This simplification cleans up the overescaping. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
2020-01-10 19:58:07 +01:00
section.item=value
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
No additional whitespace surrounds the dot or equals sign
characters. In a multiple-value item (a list), the values are
separated by semicolon characters.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
The available configuration items are described below.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**database.path**
lib: support splitting mail from database location. Introduce a new configuration value for the mail root, and use it to locate mail messages in preference to the database.path (which previously implied the mail messages were also in this location. Initially only a subset of the CLI is tested in a split configuration. Further changes will be needed for the remainder of the CLI to work in split configurations.
2020-12-31 23:20:31 +01:00
Notmuch will store its database here, (in
sub-directory named ``.notmuch`` if **database.mail\_root**
is unset).
Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
**database.mail_root**
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
The top-level directory where your mail currently exists and to
where mail will be delivered in the future. Files should be
lib: support splitting mail from database location. Introduce a new configuration value for the mail root, and use it to locate mail messages in preference to the database.path (which previously implied the mail messages were also in this location. Initially only a subset of the CLI is tested in a split configuration. Further changes will be needed for the remainder of the CLI to work in split configurations.
2020-12-31 23:20:31 +01:00
individual email messages.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
lib: support splitting mail from database location. Introduce a new configuration value for the mail root, and use it to locate mail messages in preference to the database.path (which previously implied the mail messages were also in this location. Initially only a subset of the CLI is tested in a split configuration. Further changes will be needed for the remainder of the CLI to work in split configurations.
2020-12-31 23:20:31 +01:00
History: this configuration value was introduced in notmuch 0.32.
Default: For compatibility with older configurations, the value of
database.path is used if **database.mail\_root** is unset.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
doc: describe new config framework Remove STORED IN DATABASE discussion, describe search rules. Currently profiles seem a bit pointless. They will make more sense when they apply to databases as well.
2021-01-10 16:54:35 +01:00
**database.hook_dir**
Directory containing hooks run by notmuch commands. See
**notmuch-hooks(5)**.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**user.name**
Your full name.
Default: ``$NAME`` variable if set, otherwise read from
``/etc/passwd``.
Add default configuration values to the man page
2014-10-14 16:30:56 +02:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**user.primary\_email**
Your primary email address.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
Default: ``$EMAIL`` variable if set, otherwise constructed from
the username and hostname of the current machine.
Add default configuration values to the man page
2014-10-14 16:30:56 +02:00
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**user.other\_email**
A list of other email addresses at which you receive email.
Default: not set.
**new.tags**
A list of tags that will be added to all messages incorporated by
**notmuch new**.
Default: ``unread;inbox``.
**new.ignore**
A list to specify files and directories that will not be searched
for messages by **notmuch new**. Each entry in the list is either:
A file or a directory name, without path, that will be ignored,
regardless of the location in the mail store directory hierarchy.
Or:
A regular expression delimited with // that will be matched
against the path of the file or directory relative to the database
path. Matching files and directories will be ignored. The
fix typos
2018-01-02 16:32:38 +01:00
beginning and end of string must be explicitly anchored. For
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
not "foo" or "bar/foobar".
Default: empty list.
**search.exclude\_tags**
A list of tags that will be excluded from search results by
default. Using an excluded tag in a query will override that
exclusion.
Default: empty list. Note that **notmuch-setup(1)** puts
``deleted;spam`` here when creating new configuration file.
**maildir.synchronize\_flags**
If true, then the following maildir flags (in message filenames)
will be synchronized with the corresponding notmuch tags:
+--------+-----------------------------------------------+
| Flag | Tag |
+========+===============================================+
| D | draft |
+--------+-----------------------------------------------+
| F | flagged |
+--------+-----------------------------------------------+
| P | passed |
+--------+-----------------------------------------------+
| R | replied |
+--------+-----------------------------------------------+
| S | unread (added when 'S' flag is not present) |
+--------+-----------------------------------------------+
The **notmuch new** command will notice flag changes in filenames
and update tags, while the **notmuch tag** and **notmuch restore**
commands will notice tag changes and update flags in filenames.
If there have been any changes in the maildir (new messages added,
old ones removed or renamed, maildir flags changed, etc.), it is
advisable to run **notmuch new** before **notmuch tag** or
**notmuch restore** commands to ensure the tag changes are
properly synchronized to the maildir flags, as the commands expect
the database and maildir to be in sync.
Default: ``true``.
doc: describe new config framework Remove STORED IN DATABASE discussion, describe search rules. Currently profiles seem a bit pointless. They will make more sense when they apply to databases as well.
2021-01-10 16:54:35 +01:00
**index.decrypt**
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
Policy for decrypting encrypted messages during indexing. Must be
one of: ``false``, ``auto``, ``nostash``, or ``true``.
When indexing an encrypted e-mail message, if this variable is set
to ``true``, notmuch will try to decrypt the message and index the
cleartext, stashing a copy of any discovered session keys for the
message. If ``auto``, it will try to index the cleartext if a
stashed session key is already known for the message (e.g. from a
previous copy), but will not try to access your secret keys. Use
``false`` to avoid decrypting even when a stashed session key is
already present.
``nostash`` is the same as ``true`` except that it will not stash
newly-discovered session keys in the database.
From the command line (i.e. during **notmuch-new(1)**,
**notmuch-insert(1)**, or **notmuch-reindex(1)**), the user can
override the database's stored decryption policy with the
``--decrypt=`` option.
Here is a table that summarizes the functionality of each of these
policies:
+------------------------+-------+------+---------+------+
| | false | auto | nostash | true |
+========================+=======+======+=========+======+
| Index cleartext using | | X | X | X |
| stashed session keys | | | | |
+------------------------+-------+------+---------+------+
| Index cleartext | | | X | X |
| using secret keys | | | | |
+------------------------+-------+------+---------+------+
| Stash session keys | | | | X |
+------------------------+-------+------+---------+------+
| Delete stashed session | X | | | |
| keys on reindex | | | | |
+------------------------+-------+------+---------+------+
Stashed session keys are kept in the database as properties
associated with the message. See ``session-key`` in
**notmuch-properties(7)** for more details about how they can be
useful.
Be aware that the notmuch index is likely sufficient (and a
stashed session key is certainly sufficient) to reconstruct the
cleartext of the message itself, so please ensure that the notmuch
message index is adequately protected. DO NOT USE
``index.decrypt=true`` or ``index.decrypt=nostash`` without
considering the security of your index.
Default: ``auto``.
doc: describe new config framework Remove STORED IN DATABASE discussion, describe search rules. Currently profiles seem a bit pointless. They will make more sense when they apply to databases as well.
2021-01-10 16:54:35 +01:00
**index.header.<prefix>**
doc: document user header indexing. It's a bit odd that the primary documentation is in notmuch-config, but it is consistent with the "query:" prefix.
2019-02-18 14:08:48 +01:00
Define the query prefix <prefix>, based on a mail header. For
example ``index.header.List=List-Id`` will add a probabilistic
prefix ``List:`` that searches the ``List-Id`` field. User
defined prefixes must not start with 'a'...'z'; in particular
adding a prefix with same name as a predefined prefix is not
supported. See **notmuch-search-terms(7)** for a list of existing
prefixes, and an explanation of probabilistic prefixes.
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
**built_with.<name>**
Compile time feature <name>. Current possibilities include
doc: field processor support now always included, adjust manual pages The features that require field processor support, are now just documented w/o mentioning **Xapian Field Processors**' is needed for those. Replaced "compact" and "field_processor" with "retry_lock" in build_with config option, as it is currently the only one that is optionally excluded. The former 2 are now documented as features always included. Dropped one 'we' "passive" in notmuch-search-terms.rst. It was the only one, and inconsistent with rest of the documentation in that file. Dropped message about conditional open-ended ranges support, as those are now always supported.
2020-06-02 22:21:59 +02:00
"retry_lock" (configure option, included by default).
(since notmuch 0.30, "compact" and "field_processor" are
always included.)
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
doc: describe new config framework Remove STORED IN DATABASE discussion, describe search rules. Currently profiles seem a bit pointless. They will make more sense when they apply to databases as well.
2021-01-10 16:54:35 +01:00
**query.<name>**
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
Expansion for named query called <name>. See
**notmuch-search-terms(7)** for more information about named
queries.
CLI: add notmuch-config support for named queries Most of the infrastructure here is general, only the validation/dispatch is hardcoded to a particular prefix. A notable change in behaviour is that notmuch-config now opens the database e.g. on every call to list, which fails with an error message if the database doesn't exit yet.
2016-03-22 11:54:52 +01:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
ENVIRONMENT
===========
The following environment variables can be used to control the behavior
of notmuch.
**NOTMUCH\_CONFIG**
doc: describe new config framework Remove STORED IN DATABASE discussion, describe search rules. Currently profiles seem a bit pointless. They will make more sense when they apply to databases as well.
2021-01-10 16:54:35 +01:00
Specifies the location of the notmuch configuration file.
**NOTMUCH_PROFILE**
Selects among notmuch configurations.
FILES
=====
CONFIGURATION
-------------
If ``NOTMUCH_CONFIG`` is unset, notmuch tries (in order)
- ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>`` is
defined by ``$NOTMUCH_PROFILE`` or "default"
- ``${HOME}/.notmuch-config<profile>`` where ``<profile>`` is
``.$NOTMUCH_PROFILE`` or ""
Hooks
-----
If ``database.hook_dir`` is unset, notmuch tries (in order)
- ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>`` is
defined by ``$NOTMUCH_PROFILE`` or "default"
- ``<database.path>/.notmuch/hooks``
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
SEE ALSO
========
doc: make SEE ALSO references one-per-line This will make future diffs cleaner, make it easier to keep them alphabetical, and make it easier to scan and search the documentation sources.
2017-10-17 18:57:21 +02:00
**notmuch(1)**,
**notmuch-count(1)**,
**notmuch-dump(1)**,
**notmuch-hooks(5)**,
**notmuch-insert(1)**,
**notmuch-new(1)**,
**notmuch-reply(1)**,
**notmuch-restore(1)**,
**notmuch-search(1)**,
**notmuch-search-terms(7)**,
docs: clean up documentation about decryption policies Now that the range of sensible decryption policies has come into full view, we take a bit of space to document the distinctions. Most people will use either "auto" or "true" -- but we provide "false" and "nostash" to handle use cases that might reasonably be requested. Note also that these can be combined in sensible ways. Like, if your mail comes in regularly to a service that doesn't have access to your secret keys, but does have access to your index, and you feel comfortable adding selected encrypted messages to the index after you've read them, you could stay in "auto" normally, and then when you find yourself reading an indexable message (e.g. one you want to be able to search for in the future, and that you don't mind exposing to whatever entities have access to your inde), you can do: notmuch reindex --decrypt=true id:whatever@example.biz That leaves your default the same (still "auto") but you get the cleartext index and stashed session key benefits for that particular message.
2017-12-08 07:24:03 +01:00
**notmuch-properties(7)**,
doc: make SEE ALSO references one-per-line This will make future diffs cleaner, make it easier to keep them alphabetical, and make it easier to scan and search the documentation sources.
2017-10-17 18:57:21 +02:00
**notmuch-show(1)**,
**notmuch-tag(1)**
Reference in a new issue Copy permalink