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

376 lines
12 KiB
ReStructuredText
Raw Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-config(1):
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: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. program:: config
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: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. option:: get
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: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. option:: set
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
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02: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
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
With the `--database` option, updates configuration metadata
stored in the database, rather than the default (text)
configuration file.
.. option:: list
Every configuration item is printed to stdout, each on a separate
line of the form::
section.item=value
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
doc: document (tersely) the intended behaviour of relative paths.
2021-05-07 13:02:16 +02:00
The available configuration items are described below. Non-absolute
paths are presumed relative to `$HOME` for items in section
**database**.
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: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: built_with.<name>
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Compile time feature <name>. Current possibilities include
"retry_lock" (configure option, included by default).
(since notmuch 0.30, "compact" and "field_processor" are
always included.)
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
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: database.autocommit
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: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
How often to commit transactions to disk. `0` means wait until
command completes, otherwise an integer `n` specifies to commit to
disk after every `n` completed transactions.
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
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
History: this configuration value was introduced in notmuch 0.33.
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: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: database.backup_dir
doc: document database.backup_dir Most users will not need to change this, but documenting it helps preserve the interface.
2021-05-07 13:13:22 +02:00
Directory to store tag dumps when upgrading database.
History: this configuration value was introduced in notmuch 0.32.
Default: A sibling directory of the Xapian database called
`backups`.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: database.hook_dir
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
Directory containing hooks run by notmuch commands. See
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch-hooks(5)`.
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
doc: tweak hook configuration documentation. Add a historical note, and hint to look below for more about hooks. Capitalized the heading for consistency, removed blank line.
2021-06-23 01:08:13 +02:00
History: this configuration value was introduced in notmuch 0.32.
Default: See HOOKS, below.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: database.mail_root
doc: use hyperlinks for config options in notmuch-insert(1) The tradeoff is no bold/italic in the man pages to get actual hyperlinks in the html output.
2022-02-06 15:02:37 +01:00
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
The top-level directory where your mail currently exists and to
where mail will be delivered in the future. Files should be
individual email messages.
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: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
History: this configuration value was introduced in notmuch 0.32.
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: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Default: For compatibility with older configurations, the value of
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
database.path is used if :nmconfig:`database.mail_root` is unset.
.. nmconfig:: database.path
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: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Notmuch will store its database here, (in
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
sub-directory named ``.notmuch`` if :nmconfig:`database.mail_root`
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
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: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Default: see :ref:`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
CLI/git: support configuration for repo location / prefix This is probably more convenient than always passing a command line argument. Use notmuch-config for consistency with other notmuch CLI tools. Now that there is something relevant in the config files, test the --config option.
2022-05-10 12:32:48 +02:00
.. nmconfig:: git.path
Default location for git repository for :any:`notmuch-git`.
CLI/git: add safety checks for checkout and commit Commits or checkouts that modify a large fraction of the messages in the database should be relatively rare (and in some automated process, probably non-existent). For initial setup, where such operations are expected, the user can pass --force.
2022-05-14 20:25:47 +02:00
.. nmconfig:: git.safe_fraction
Some :any:`notmuch-git` operations check that the fraction of
messages changed (in the database or in git, as appropriate) is not
too large. This item controls what fraction of total messages is
considered "not too large".
CLI/git: support configuration for repo location / prefix This is probably more convenient than always passing a command line argument. Use notmuch-config for consistency with other notmuch CLI tools. Now that there is something relevant in the config files, test the --config option.
2022-05-10 12:32:48 +02:00
.. nmconfig:: git.tag_prefix
Default tag prefix (filter) for :any:`notmuch-git`.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: index.decrypt
doc: add configuration section to notmuch-new(1) Increase discoverability.
2022-02-06 14:28:14 +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
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.
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
From the command line (i.e. during :any:`notmuch-new(1)`,
:any:`notmuch-insert(1)`, or :any:`notmuch-reindex(1)`), the user can
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
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
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch-properties(7)` for more details about how they can be
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
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: add configuration section to notmuch-new(1) Increase discoverability.
2022-02-06 14:28:14 +01:00
.. _index.header:
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: 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
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
supported. See :any:`notmuch-search-terms(7)` for a list of existing
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
prefixes, and an explanation of probabilistic prefixes.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: maildir.synchronize_flags
doc: add configuration section to notmuch-new(1) Increase discoverability.
2022-02-06 14:28:14 +01:00
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
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 :any:`notmuch-new(1)` command will notice flag changes in
filenames and update tags, while the :any:`notmuch-tag(1)` and
:any:`notmuch-restore(1)` 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 :any:`notmuch-new(1)` before
:any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` 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: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: new.ignore
doc: add configuration section to notmuch-new(1) Increase discoverability.
2022-02-06 14:28:14 +01:00
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
A list to specify files and directories that will not be searched
for messages by :any:`notmuch-new(1)`. 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
beginning and end of string must be explicitly anchored. For
example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
not "foo" or "bar/foobar".
Default: empty list.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: new.tags
doc: add configuration section to notmuch-new(1) Increase discoverability.
2022-02-06 14:28:14 +01:00
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
A list of tags that will be added to all messages incorporated by
**notmuch new**.
Default: ``unread;inbox``.
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: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: 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
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch-search-terms(7)` for more information about named
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
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: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: search.exclude_tags
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
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 :any:`notmuch-setup(1)` puts
``deleted;spam`` here when creating new configuration file.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: show.extra_headers
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
By default :any:`notmuch-show(1)` includes the following headers
in structured output if they are present in the message:
`Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
option allows the specification of a list of further
headers to output.
History: This configuration value was introduced in notmuch 0.35.
Default: empty list.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: squery.<name>
CLI/config support saving s-expression queries This commit does not enable using saved s-expression queries, only saving and retrieving them from the config file or the database. Use in queries will be enabled in a following commit.
2021-08-24 17:17:38 +02:00
Expansion for named query called <name>, using s-expression syntax. See
:any:`notmuch-sexp-queries(7)` for more information about s-expression
queries.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: user.name
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Your full name.
Default: ``$NAME`` variable if set, otherwise read from
``/etc/passwd``.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: user.other_email
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
A list of other email addresses at which you receive email
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
(see also, :nmconfig:`user.primary_email`)
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Default: not set.
doc: define and use semantic markup for configuration items This makes sure each configuration item is cross referenceable without extra markup, and also adds index entries.
2022-05-12 13:52:30 +02:00
.. nmconfig:: user.primary_email
doc: alphabetize options in notmuch-config(1) Originally (I think) these were in the order generated by notmuch setup. As the number of options grows, and several are not in the initial setup generated file, the original order becomes less useful for users. This commit alphabetizes the keys to help users search. There is only one content change, an added cross-reference from user.other_email to user.primary_email.
2022-02-06 14:07:13 +01:00
Your primary email address.
Default: ``$EMAIL`` variable if set, otherwise constructed from
the username and hostname of the current machine.
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
FILES
=====
python-cffi: switch to notmuch_database_{open,create}_with_config Since release 0.32, libnotmuch provides searching for database and configuration paths. This commit changes the python module notmuch2 to use those facilities. This fixes the bug reported in [1], along with a couple of the deprecation warnings in the python bindings. Database.default_path is deprecated, since it no longer faithfully reflects what libnotmuch is doing, and it is also no longer used in the bindings themselves. This commit choose the default of config=CONFIG.EMPTY (equivalent to passing "" to notmuch_database_open_with_config). This makes the change upward compatible API-wise (at least as far as the test suite verifies), but changing the default to CONFIG.SEARCH would probably be more convenient for bindings users. [1]: id:87h7d4wp6b.fsf@tethera.net
2021-10-30 18:22:35 +02:00
.. _config_search:
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
CONFIGURATION
-------------
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
Notmuch configuration file search order:
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
doc: example command-line option reference Example reference to a command-line option using the option role reference. This creates a hyperlink in html, and the usual boldface style in man page. This could be used throughout the man pages.
2021-05-21 22:44:13 +02:00
1. File specified by :option:`notmuch --config` global option; see
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
:any:`notmuch(1)`.
2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
3. ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>``
is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise.
4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
by :envvar:`NOTMUCH_PROFILE` environment variable if set,
``$HOME/.notmuch-config`` otherwise.
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
doc: document database search algorithm. Essentially a translation of the function _choose_database_path for human consumption. As a bonus, document environment variable NOTMUCH_DATABASE
2021-08-04 12:42:36 +02:00
.. _database:
DATABASE LOCATION
-----------------
Notmuch database search order:
1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable.
2. Directory specified by config key ``database.path``.
3. ``$XDG_DATA_HOME/notmuch/<profile>`` where ``<profile>``
is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
set, ``$XDG_DATA_HOME/notmuch/default`` otherwise.
4. Directory specified by :envvar:`MAILDIR` environment variable.
5. ``$HOME/mail``
doc: tweak hook configuration documentation. Add a historical note, and hint to look below for more about hooks. Capitalized the heading for consistency, removed blank line.
2021-06-23 01:08:13 +02:00
HOOKS
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
-----
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
Notmuch hook directory search order:
1. Directory specified by ``database.hook_dir`` configuration option.
2. ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>``
is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise.
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
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
3. ``<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: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch(1)`,
:any:`notmuch-count(1)`,
:any:`notmuch-dump(1)`,
:any:`notmuch-hooks(5)`,
:any:`notmuch-insert(1)`,
:any:`notmuch-new(1)`,
:any:`notmuch-properties(7)`,
:any:`notmuch-reply(1)`,
:any:`notmuch-restore(1)`,
:any:`notmuch-search(1)`,
:any:`notmuch-search-terms(7)`,
:any:`notmuch-show(1)`,
:any:`notmuch-tag(1)`
Reference in a new issue Copy permalink