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

347 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: 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
built_with.<name>
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: 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
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: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
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: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
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: 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
database.mail_root
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
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: 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
database.path
Notmuch will store its database here, (in
sub-directory named ``.notmuch`` 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: 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
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02: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.
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: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02: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
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: 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
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 :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``.
new.ignore
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.
new.tags
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: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02: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
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: 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
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 :any:`notmuch-setup(1)` puts
``deleted;spam`` here when creating new configuration file.
.. _show.extra_headers:
show.extra\_headers
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: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
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: 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
user.name
Your full name.
Default: ``$NAME`` variable if set, otherwise read from
``/etc/passwd``.
user.other\_email
A list of other email addresses at which you receive email
(see also, :ref:`user.primary_email <user.primary_email>`).
Default: not set.
.. _user.primary_email:
user.primary\_email
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