- libxapian-dev
- libgmime-2.6-dev
- libtalloc-dev
- - python-sphinx
- - gdb
+ - python3-sphinx
- gpgsm
script:
-------------------------------------
On a modern, package-based operating system you can install all of the
-dependencies with a simple simple command line. For example:
+dependencies with a single simple command line. For example:
For Debian and similar:
- sudo apt-get install libxapian-dev libgmime-3.0-dev libtalloc-dev zlib1g-dev python-sphinx
+ sudo apt-get install libxapian-dev libgmime-3.0-dev libtalloc-dev zlib1g-dev python3-sphinx
For Fedora and similar:
- sudo yum install xapian-core-devel gmime-devel libtalloc-devel zlib-devel python-sphinx
+ sudo yum install xapian-core-devel gmime-devel libtalloc-devel zlib-devel python3-sphinx
On other systems, a similar command can be used, but the details of
the package names may be different.
echo "Refusing to replace an existing release."; \
echo "Don't forget to update \"version\" as described in RELEASING before release." ; \
false ;; \
- *) echo "An unexpected error occured"; \
+ *) echo "An unexpected error occurred"; \
false;; esac
# The user has not set any verbosity, default to quiet mode and inform the
Previously, it was impossible to open writable database handles,
because `DATABASE_MODE_READ_ONLY` and `DATABASE_MODE_READ_WRITE` were
both set to zero.
- The same issue occured with sort modes.
+ The same issue occurred with sort modes.
Notmuch 0.22.2 (2016-09-08)
===========================
Emacs
-----
-Avoid rendering large text attachements.
+Avoid rendering large text attachments.
Improved rendering of CID references in HTML.
Sphinx is now mandatory to build docs
Support for using rst2man in place of sphinx to build the
- docmumentation has been removed.
+ documentation has been removed.
Improved notmuch-search-terms.7
The commands set consistent exit status codes on failures
The cli commands now consistently set exit status of 1 on failures,
- except where explicitly otherwise noted. The notable expections are
+ except where explicitly otherwise noted. The notable exceptions are
the status codes for format version mismatches for commands that
support formatted output.
Add keybinding ('c I') for stashing Message-ID's without an id: prefix
- Reduces manual labour when stashing them for use outside notmuch.
+ Reduces manual labor when stashing them for use outside notmuch.
Do not query on `notmuch-search` exit
nmbug - share tags with a given prefix
nmbug helps maintain a git repo containing all tags with a given
- prefix (by default "notmuch::"). Tags can be shared by commiting
+ prefix (by default "notmuch::"). Tags can be shared by committing
them to git in one location and restoring in another.
Notmuch 0.9 (2011-10-01)
iterator and broke list(Filenames()). Use `len(list(names))`
instead.
-:class:`Directoy` -- A directory entry in the database
+:class:`Directory` -- A directory entry in the database
------------------------------------------------------
.. autoclass:: Directory
:returns: :class:`Message` or `None` if no message is found.
:raises:
:exc:`OutOfMemoryError`
- If an Out-of-memory occured while constructing the message.
+ If an Out-of-memory occurred while constructing the message.
:exc:`XapianError`
In case of a Xapian Exception. These exceptions
include "Database modified" situations, e.g. when the
function returns None if no message is found with the given
filename.
- :raises: :exc:`OutOfMemoryError` if an Out-of-memory occured while
+ :raises: :exc:`OutOfMemoryError` if an Out-of-memory occurred while
constructing the message.
:raises: :exc:`XapianError` in case of a Xapian Exception.
These exceptions include "Database modified"
def __init__(self, files_p, parent):
"""
:param files_p: A pointer to an underlying *notmuch_tags_t*
- structure. These are not publically exposed, so a user
+ structure. These are not publicly exposed, so a user
will almost never instantiate a :class:`Tags` object
herself. They are usually handed back as a result,
e.g. in :meth:`Database.get_all_tags`. *tags_p* must be
:returns: The header value as string
:raises: :exc:`NotInitializedError` if the message is not
initialized
- :raises: :exc:`NullPointerError` if any error occured
+ :raises: :exc:`NullPointerError` if any error occurred
"""
if not self._msg:
raise NotInitializedError()
:returns: A :class:`Tags` iterator.
:raises: :exc:`NotInitializedError` if the message is not
initialized
- :raises: :exc:`NullPointerError` if any error occured
+ :raises: :exc:`NullPointerError` if any error occurred
"""
if not self._msg:
raise NotInitializedError()
def __init__(self, msgs_p, parent=None):
"""
:param msgs_p: A pointer to an underlying *notmuch_messages_t*
- structure. These are not publically exposed, so a user
+ structure. These are not publicly exposed, so a user
will almost never instantiate a :class:`Messages` object
herself. They are usually handed back as a result,
e.g. in :meth:`Query.search_messages`. *msgs_p* must be
def __init__(self, tags_p, parent=None):
"""
:param tags_p: A pointer to an underlying *notmuch_tags_t*
- structure. These are not publically exposed, so a user
+ structure. These are not publicly exposed, so a user
will almost never instantiate a :class:`Tags` object
herself. They are usually handed back as a result,
e.g. in :meth:`Database.get_all_tags`. *tags_p* must be
def __init__(self, thread_p, parent=None):
"""
:param thread_p: A pointer to an internal notmuch_thread_t
- Structure. These are not publically exposed, so a user
+ Structure. These are not publicly exposed, so a user
will almost never instantiate a :class:`Thread` object
herself. They are usually handed back as a result,
e.g. when iterating through :class:`Threads`. *thread_p*
def __init__(self, threads_p, parent=None):
"""
:param threads_p: A pointer to an underlying *notmuch_threads_t*
- structure. These are not publically exposed, so a user
+ structure. These are not publicly exposed, so a user
will almost never instantiate a :class:`Threads` object
herself. They are usually handed back as a result,
e.g. in :meth:`Query.search_threads`. *threads_p* must be
*
* It's not strictly necessary to call this function. All memory from
* the notmuch_threads_t object will be reclaimed when the
- * containg query object is destroyed.
+ * containing query object is destroyed.
*/
func (self *Threads) Destroy() {
if self.threads != nil {
return ""
}
id := C.notmuch_message_get_message_id(self.message)
- // we dont own id
+ // we don't own id
// defer C.free(unsafe.Pointer(id))
if id == nil {
return ""
return ""
}
id := C.notmuch_message_get_thread_id(self.message)
- // we dont own id
+ // we don't own id
// defer C.free(unsafe.Pointer(id))
if id == nil {
return ""
}
fname := C.notmuch_message_get_filename(self.message)
- // we dont own fname
+ // we don't own fname
// defer C.free(unsafe.Pointer(fname))
if fname == nil {
var c_header *C.char = C.CString(header)
defer C.free(unsafe.Pointer(c_header))
- /* we dont own value */
+ /* we don't own value */
value := C.notmuch_message_get_header(self.message, c_header)
if value == nil {
return ""
return ""
}
s := C.notmuch_tags_get(self.tags)
- // we dont own 's'
+ // we don't own 's'
return C.GoString(s)
}
notmuch (0.18-2) unstable; urgency=medium
* Disable atomicity tests on armhf. These should be re-enabled when
- upstream relases a fix for this (in progress).
+ upstream releases a fix for this (in progress).
-- David Bremner <bremner@debian.org> Thu, 08 May 2014 08:28:33 +0900
notmuch (0.6) unstable; urgency=low
* New upstream release; see /usr/share/doc/notmuch/NEWS for
- details. Hilights include:
+ details. Highlights include:
- Folder-based search (Closes: #597222)
- PGP/MIME decryption and verification
* Document strict dependency on emacs23 (Closes: #631994).
# The default branch for the debian patch (no patch in our case)
debian-branch = master
-# Directory for performing the build
-export-dir = ./debian-build
-
# Format for upstream tags
upstream-tag = %(version)s
exit 1
fi
else
- echo "Reading './version' file failed (suprisingly!)"
+ echo "Reading './version' file failed (surprisingly!)"
exit 1
fi < ./version
else
build-man: ${MAN_GZIP_FILES}
install-man: ${MAN_GZIP_FILES}
- mkdir -p "$(DESTDIR)$(mandir)/man1"
- mkdir -p "$(DESTDIR)$(mandir)/man5"
- mkdir -p "$(DESTDIR)$(mandir)/man7"
+ mkdir -m0755 -p "$(DESTDIR)$(mandir)/man1"
+ mkdir -m0755 -p "$(DESTDIR)$(mandir)/man5"
+ mkdir -m0755 -p "$(DESTDIR)$(mandir)/man7"
install -m0644 $(filter %.1.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man1
install -m0644 $(filter %.5.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man5
install -m0644 $(filter %.7.gz,$(MAN_GZIP_FILES)) $(DESTDIR)/$(mandir)/man7
Supported options for **address** include
- ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
- Presents the results in either JSON, S-Expressions, newline
- character separated plain-text (default), or null character
- separated plain-text (compatible with **xargs(1)** -0 option
- where available).
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- omitted, the latest supported version will be used.
-
- ``--output=(sender|recipients|count|address)``
-
- Controls which information appears in the output. This option
- can be given multiple times to combine different outputs.
- When neither --output=sender nor --output=recipients is
- given, --output=sender is implied.
-
- **sender**
- Output all addresses from the *From* header.
-
- Note: Searching for **sender** should be much faster than
- searching for **recipients**, because sender addresses are
- cached directly in the database whereas other addresses
- need to be fetched from message files.
-
- **recipients**
- Output all addresses from the *To*, *Cc* and *Bcc*
- headers.
-
- **count**
- Print the count of how many times was the address
- encountered during search.
-
- Note: With this option, addresses are printed only after
- the whole search is finished. This may take long time.
-
- **address**
- Output only the email addresses instead of the full
- mailboxes with names and email addresses. This option has
- no effect on the JSON or S-Expression output formats.
-
- ``--deduplicate=(no|mailbox|address)``
-
- Control the deduplication of results.
-
- **no**
- Output all occurrences of addresses in the matching
- messages. This is not applicable with --output=count.
-
- **mailbox**
- Deduplicate addresses based on the full, case sensitive
- name and email address, or mailbox. This is effectively
- the same as piping the --deduplicate=no output to **sort |
- uniq**, except for the order of results. This is the
- default.
-
- **address**
- Deduplicate addresses based on the case insensitive
- address part of the mailbox. Of all the variants (with
- different name or case), print the one occurring most
- frequently among the matching messages. If --output=count
- is specified, include all variants in the count.
-
- ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
- This option can be used to present results in either
- chronological order (**oldest-first**) or reverse chronological
- order (**newest-first**).
-
- By default, results will be displayed in reverse chronological
- order, (that is, the newest results will be displayed first).
-
- However, if either --output=count or --deduplicate=address is
- specified, this option is ignored and the order of the results
- is unspecified.
-
- ``--exclude=(true|false)``
- A message is called "excluded" if it matches at least one tag in
- search.tag\_exclude that does not appear explicitly in the
- search terms. This option specifies whether to omit excluded
- messages in the search process.
-
- The default value, **true**, prevents excluded messages from
- matching the search terms.
-
- **false** allows excluded messages to match search terms and
- appear in displayed results.
+``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
+ Presents the results in either JSON, S-Expressions, newline
+ character separated plain-text (default), or null character
+ separated plain-text (compatible with **xargs(1)** -0 option where
+ available).
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ omitted, the latest supported version will be used.
+
+``--output=(sender|recipients|count|address)``
+ Controls which information appears in the output. This option can
+ be given multiple times to combine different outputs. When
+ neither --output=sender nor --output=recipients is
+ given, --output=sender is implied.
+
+ **sender**
+ Output all addresses from the *From* header.
+
+ Note: Searching for **sender** should be much faster than
+ searching for **recipients**, because sender addresses are
+ cached directly in the database whereas other addresses need
+ to be fetched from message files.
+
+ **recipients**
+ Output all addresses from the *To*, *Cc* and *Bcc* headers.
+
+ **count**
+ Print the count of how many times was the address encountered
+ during search.
+
+ Note: With this option, addresses are printed only after the
+ whole search is finished. This may take long time.
+
+ **address**
+ Output only the email addresses instead of the full mailboxes
+ with names and email addresses. This option has no effect on
+ the JSON or S-Expression output formats.
+
+``--deduplicate=(no|mailbox|address)``
+ Control the deduplication of results.
+
+ **no**
+ Output all occurrences of addresses in the matching
+ messages. This is not applicable with --output=count.
+
+ **mailbox**
+ Deduplicate addresses based on the full, case sensitive name
+ and email address, or mailbox. This is effectively the same as
+ piping the --deduplicate=no output to **sort | uniq**, except
+ for the order of results. This is the default.
+
+ **address**
+ Deduplicate addresses based on the case insensitive address
+ part of the mailbox. Of all the variants (with different name
+ or case), print the one occurring most frequently among the
+ matching messages. If --output=count is specified, include all
+ variants in the count.
+
+``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+ This option can be used to present results in either chronological
+ order (**oldest-first**) or reverse chronological order
+ (**newest-first**).
+
+ By default, results will be displayed in reverse chronological
+ order, (that is, the newest results will be displayed first).
+
+ However, if either --output=count or --deduplicate=address is
+ specified, this option is ignored and the order of the results is
+ unspecified.
+
+``--exclude=(true|false)``
+ A message is called "excluded" if it matches at least one tag in
+ search.tag\_exclude that does not appear explicitly in the search
+ terms. This option specifies whether to omit excluded messages in
+ the search process.
+
+ The default value, **true**, prevents excluded messages from
+ matching the search terms.
+
+ **false** allows excluded messages to match search terms and
+ appear in displayed results.
EXIT STATUS
===========
Supported options for **compact** include
- ``--backup=``\ <directory>
- Save the current database to the given directory before
- replacing it with the compacted database. The backup directory
- must not exist and it must reside on the same mounted filesystem
- as the current database.
-
- ``--quiet``
- Do not report database compaction progress to stdout.
+``--backup=``\ <directory>
+ Save the current database to the given directory before replacing
+ it with the compacted database. The backup directory must not
+ exist and it must reside on the same mounted filesystem as the
+ current database.
+
+``--quiet``
+ Do not report database compaction progress to stdout.
ENVIRONMENT
===========
should not be placed in the configuration file, and should be accessed
programmatically as described in the SYNOPSIS above.
- **get**
- The value of the specified configuration item is printed to
- stdout. If the item has multiple values (it is a list), each
- value is separated by a newline character.
+**get**
+ The value of the specified configuration item is printed to
+ stdout. If the item has multiple values (it is a list), each value
+ is separated by a newline character.
- **set**
- The specified configuration item is set to the given value. To
- specify a multiple-value item (a list), provide each value as a
- separate command-line argument.
+**set**
+ The specified configuration item is set to the given value. To
+ specify a multiple-value item (a list), provide each value as a
+ separate command-line argument.
- If no values are provided, the specified configuration item will
- be removed from the configuration file.
+ If no values are provided, the specified configuration item will
+ be removed from the configuration file.
- **list**
- Every configuration item is printed to stdout, each on a
- separate line of the form:
+**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.
+ No additional whitespace surrounds the dot or equals sign
+ characters. In a multiple-value item (a list), the values are
+ separated by semicolon characters.
The available configuration items are described below.
- **database.path**
- 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. Notmuch will store its database
- within a sub-directory of the path configured here named
- ``.notmuch``.
+**database.path**
+ 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. Notmuch will store its database within
+ a sub-directory of the path configured here named ``.notmuch``.
- Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
+ Default: ``$MAILDIR`` variable if set, otherwise ``$HOME/mail``.
+
+**user.name**
+ Your full name.
+
+ Default: ``$NAME`` variable if set, otherwise read from
+ ``/etc/passwd``.
- **user.name**
- Your full name.
+**user.primary\_email**
+ Your primary email address.
- Default: ``$NAME`` variable if set, otherwise read from
- ``/etc/passwd``.
+ Default: ``$EMAIL`` variable if set, otherwise constructed from
+ the username and hostname of the current machine.
- **user.primary\_email**
- Your primary email address.
-
- Default: ``$EMAIL`` variable if set, otherwise constructed from the
- username and hostname of the current machine.
-
- **user.other\_email**
- A list of other email addresses at which you receive email.
-
- Default: not set.
-
- **new.tags**
- A list of tags that will be added to all messages incorporated
- by **notmuch new**.
-
- Default: ``unread;inbox``.
-
- **new.ignore**
- A list to specify files and directories that will not be
- searched for messages by **notmuch new**. Each entry in the
- list is either:
-
- A file or a directory name, without path, that will be
- ignored, regardless of the location in the mail store
- directory hierarchy.
-
- Or:
-
- A regular expression delimited with // that will be matched
- against the path of the file or directory relative to the
- database path. Matching files and directories will be
- ignored. The beginning and end of string must be explictly
- anchored. For example, /.*/foo$/ would match "bar/foo" and
- "bar/baz/foo", but not "foo" or "bar/foobar".
-
- Default: empty list.
-
- **search.exclude\_tags**
- A list of tags that will be excluded from search results by
- default. Using an excluded tag in a query will override that
- exclusion.
-
- Default: empty list. Note that **notmuch-setup(1)** puts
- ``deleted;spam`` here when creating new configuration file.
-
-
-
- **maildir.synchronize\_flags**
- If true, then the following maildir flags (in message filenames)
- will be synchronized with the corresponding notmuch tags:
-
- +--------+-----------------------------------------------+
- | Flag | Tag |
- +========+===============================================+
- | D | draft |
- +--------+-----------------------------------------------+
- | F | flagged |
- +--------+-----------------------------------------------+
- | P | passed |
- +--------+-----------------------------------------------+
- | R | replied |
- +--------+-----------------------------------------------+
- | S | unread (added when 'S' flag is not present) |
- +--------+-----------------------------------------------+
-
- The **notmuch new** command will notice flag changes in
- filenames and update tags, while the **notmuch tag** and
- **notmuch restore** commands will notice tag changes and update
- flags in filenames.
-
- If there have been any changes in the maildir (new messages
- added, old ones removed or renamed, maildir flags changed,
- etc.), it is advisable to run **notmuch new** before **notmuch
- tag** or **notmuch restore** commands to ensure the tag changes
- are properly synchronized to the maildir flags, as the commands
- expect the database and maildir to be in sync.
-
- Default: ``true``.
-
- **crypto.gpg_path**
-
- Name (or full path) of gpg binary to use in verification and
- decryption of PGP/MIME messages. NOTE: This configuration
- item is deprecated, and will be ignored if notmuch is built
- against GMime 3.0 or later.
-
- Default: ``gpg``.
-
- **index.decrypt**
-
- **[STORED IN DATABASE]**
-
- Policy for decrypting encrypted messages during indexing.
- Must be one of: ``false``, ``auto``, ``nostash``, or
- ``true``.
-
- When indexing an encrypted e-mail message, if this variable is
- set to ``true``, notmuch will try to decrypt the message and
- index the cleartext, stashing a copy of any discovered session
- keys for the message. If ``auto``, it will try to index the
- cleartext if a stashed session key is already known for the message
- (e.g. from a previous copy), but will not try to access your
- secret keys. Use ``false`` to avoid decrypting even when a
- stashed session key is already present.
-
- ``nostash`` is the same as ``true`` except that it will not
- stash newly-discovered session keys in the database.
-
- From the command line (i.e. during **notmuch-new(1)**,
- **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user
- can override the database's stored decryption policy with the
- ``--decrypt=`` option.
-
- Here is a table that summarizes the functionality of each of
- these policies:
-
- +------------------------+-------+------+---------+------+
- | | false | auto | nostash | true |
- +========================+=======+======+=========+======+
- | Index cleartext using | | X | X | X |
- | stashed session keys | | | | |
- +------------------------+-------+------+---------+------+
- | Index cleartext | | | X | X |
- | using secret keys | | | | |
- +------------------------+-------+------+---------+------+
- | Stash session keys | | | | X |
- +------------------------+-------+------+---------+------+
- | Delete stashed session | X | | | |
- | keys on reindex | | | | |
- +------------------------+-------+------+---------+------+
-
- Stashed session keys are kept in the database as properties
- associated with the message. See ``session-key`` in
- **notmuch-properties(7)** for more details about how they can
- be useful.
-
- Be aware that the notmuch index is likely sufficient (and a
- stashed session key is certainly sufficient) to reconstruct
- the cleartext of the message itself, so please ensure that the
- notmuch message index is adequately protected. DO NOT USE
- ``index.decrypt=true`` or ``index.decrypt=nostash`` without
- considering the security of your index.
-
- Default: ``auto``.
-
- **built_with.<name>**
-
- Compile time feature <name>. Current possibilities include
- "compact" (see **notmuch-compact(1)**)
- and "field_processor" (see **notmuch-search-terms(7)**).
-
- **query.<name>**
-
- **[STORED IN DATABASE]**
- Expansion for named query called <name>. See
- **notmuch-search-terms(7)** for more information about named
- queries.
+**user.other\_email**
+ A list of other email addresses at which you receive email.
+
+ Default: not set.
+
+**new.tags**
+ A list of tags that will be added to all messages incorporated by
+ **notmuch new**.
+
+ Default: ``unread;inbox``.
+
+**new.ignore**
+ A list to specify files and directories that will not be searched
+ for messages by **notmuch new**. Each entry in the list is either:
+
+ A file or a directory name, without path, that will be ignored,
+ regardless of the location in the mail store directory hierarchy.
+
+ Or:
+
+ A regular expression delimited with // that will be matched
+ against the path of the file or directory relative to the database
+ path. Matching files and directories will be ignored. The
+ 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.
+
+**search.exclude\_tags**
+ A list of tags that will be excluded from search results by
+ default. Using an excluded tag in a query will override that
+ exclusion.
+
+ Default: empty list. Note that **notmuch-setup(1)** puts
+ ``deleted;spam`` here when creating new configuration file.
+
+**maildir.synchronize\_flags**
+ If true, then the following maildir flags (in message filenames)
+ will be synchronized with the corresponding notmuch tags:
+
+ +--------+-----------------------------------------------+
+ | Flag | Tag |
+ +========+===============================================+
+ | D | draft |
+ +--------+-----------------------------------------------+
+ | F | flagged |
+ +--------+-----------------------------------------------+
+ | P | passed |
+ +--------+-----------------------------------------------+
+ | R | replied |
+ +--------+-----------------------------------------------+
+ | S | unread (added when 'S' flag is not present) |
+ +--------+-----------------------------------------------+
+
+ The **notmuch new** command will notice flag changes in filenames
+ and update tags, while the **notmuch tag** and **notmuch restore**
+ commands will notice tag changes and update flags in filenames.
+
+ If there have been any changes in the maildir (new messages added,
+ old ones removed or renamed, maildir flags changed, etc.), it is
+ advisable to run **notmuch new** before **notmuch tag** or
+ **notmuch restore** commands to ensure the tag changes are
+ properly synchronized to the maildir flags, as the commands expect
+ the database and maildir to be in sync.
+
+ Default: ``true``.
+
+**crypto.gpg_path**
+ Name (or full path) of gpg binary to use in verification and
+ decryption of PGP/MIME messages. NOTE: This configuration item is
+ deprecated, and will be ignored if notmuch is built against GMime
+ 3.0 or later.
+
+ Default: ``gpg``.
+
+**index.decrypt** **[STORED IN DATABASE]**
+ Policy for decrypting encrypted messages during indexing. Must be
+ one of: ``false``, ``auto``, ``nostash``, or ``true``.
+
+ When indexing an encrypted e-mail message, if this variable is set
+ to ``true``, notmuch will try to decrypt the message and index the
+ cleartext, stashing a copy of any discovered session keys for the
+ message. If ``auto``, it will try to index the cleartext if a
+ stashed session key is already known for the message (e.g. from a
+ previous copy), but will not try to access your secret keys. Use
+ ``false`` to avoid decrypting even when a stashed session key is
+ already present.
+
+ ``nostash`` is the same as ``true`` except that it will not stash
+ newly-discovered session keys in the database.
+
+ From the command line (i.e. during **notmuch-new(1)**,
+ **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user can
+ override the database's stored decryption policy with the
+ ``--decrypt=`` option.
+
+ Here is a table that summarizes the functionality of each of these
+ policies:
+
+ +------------------------+-------+------+---------+------+
+ | | false | auto | nostash | true |
+ +========================+=======+======+=========+======+
+ | Index cleartext using | | X | X | X |
+ | stashed session keys | | | | |
+ +------------------------+-------+------+---------+------+
+ | Index cleartext | | | X | X |
+ | using secret keys | | | | |
+ +------------------------+-------+------+---------+------+
+ | Stash session keys | | | | X |
+ +------------------------+-------+------+---------+------+
+ | Delete stashed session | X | | | |
+ | keys on reindex | | | | |
+ +------------------------+-------+------+---------+------+
+
+ Stashed session keys are kept in the database as properties
+ associated with the message. See ``session-key`` in
+ **notmuch-properties(7)** for more details about how they can be
+ useful.
+
+ Be aware that the notmuch index is likely sufficient (and a
+ stashed session key is certainly sufficient) to reconstruct the
+ cleartext of the message itself, so please ensure that the notmuch
+ message index is adequately protected. DO NOT USE
+ ``index.decrypt=true`` or ``index.decrypt=nostash`` without
+ considering the security of your index.
+
+ Default: ``auto``.
+
+**built_with.<name>**
+ Compile time feature <name>. Current possibilities include
+ "compact" (see **notmuch-compact(1)**) and "field_processor" (see
+ **notmuch-search-terms(7)**).
+
+**query.<name>** **[STORED IN DATABASE]**
+ Expansion for named query called <name>. See
+ **notmuch-search-terms(7)** for more information about named
+ queries.
ENVIRONMENT
===========
Supported options for **count** include
- ``--output=(messages|threads|files)``
-
- **messages**
- Output the number of matching messages. This is the default.
-
- **threads**
- Output the number of matching threads.
-
- **files**
- Output the number of files associated with matching
- messages. This may be bigger than the number of matching
- messages due to duplicates (i.e. multiple files having the
- same message-id).
-
- ``--exclude=(true|false)``
- Specify whether to omit messages matching search.tag\_exclude
- from the count (the default) or not.
-
- ``--batch``
- Read queries from a file (stdin by default), one per line, and
- output the number of matching messages (or threads) to stdout,
- one per line. On an empty input line the count of all messages
- (or threads) in the database will be output. This option is not
- compatible with specifying search terms on the command line.
-
- ``--lastmod``
- Append lastmod (counter for number of database updates) and UUID
- to the output. lastmod values are only comparable between databases
- with the same UUID.
-
- ``--input=``\ <filename>
- Read input from given file, instead of from stdin. Implies
- ``--batch``.
+``--output=(messages|threads|files)``
+ **messages**
+ Output the number of matching messages. This is the default.
+
+ **threads**
+ Output the number of matching threads.
+
+ **files**
+ Output the number of files associated with matching
+ messages. This may be bigger than the number of matching
+ messages due to duplicates (i.e. multiple files having the
+ same message-id).
+
+``--exclude=(true|false)``
+ Specify whether to omit messages matching search.tag\_exclude from
+ the count (the default) or not.
+
+``--batch``
+ Read queries from a file (stdin by default), one per line, and
+ output the number of matching messages (or threads) to stdout, one
+ per line. On an empty input line the count of all messages (or
+ threads) in the database will be output. This option is not
+ compatible with specifying search terms on the command line.
+
+``--lastmod``
+ Append lastmod (counter for number of database updates) and UUID
+ to the output. lastmod values are only comparable between
+ databases with the same UUID.
+
+``--input=``\ <filename>
+ Read input from given file, instead of from stdin. Implies
+ ``--batch``.
SEE ALSO
========
Supported options for **dump** include
- ``--gzip``
- Compress the output in a format compatible with **gzip(1)**.
-
- ``--format=(sup|batch-tag)``
- Notmuch restore supports two plain text dump formats, both with one
- message-id per line, followed by a list of tags.
-
- **batch-tag**
-
- The default **batch-tag** dump format is intended to more
- robust against malformed message-ids and tags containing
- whitespace or non-\ **ascii(7)** characters. Each line has
- the form
-
- +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
- id:<*quoted-message-id*\ >
-
- Tags are hex-encoded by replacing every byte not matching
- the regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is
- the two digit hex encoding. The message ID is a valid
- Xapian query, quoted using Xapian boolean term quoting
- rules: if the ID contains whitespace or a close paren or
- starts with a double quote, it must be enclosed in double
- quotes and double quotes inside the ID must be
- doubled. The astute reader will notice this is a special
- case of the batch input format for **notmuch-tag(1)**;
- note that the single message-id query is mandatory for
- **notmuch-restore(1)**.
-
- **sup**
-
- The **sup** dump file format is specifically chosen to be
- compatible with the format of files produced by
- sup-dump. So if you've previously been using sup for mail,
- then the **notmuch restore** command provides you a way to
- import all of your tags (or labels as sup calls
- them). Each line has the following form
-
- <*message-id*\ > **(** <*tag*\ > ... **)**
-
- with zero or more tags are separated by spaces. Note that
- (malformed) message-ids may contain arbitrary non-null
- characters. Note also that tags with spaces will not be
- correctly restored with this format.
-
- ``--include=(config|properties|tags)``
-
+``--gzip``
+ Compress the output in a format compatible with **gzip(1)**.
+
+``--format=(sup|batch-tag)``
+ Notmuch restore supports two plain text dump formats, both with
+ one message-id per line, followed by a list of tags.
+
+ **batch-tag**
+ The default **batch-tag** dump format is intended to more
+ robust against malformed message-ids and tags containing
+ whitespace or non-\ **ascii(7)** characters. Each line has the
+ form::
+
+ +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ >
+
+ Tags are hex-encoded by replacing every byte not matching the
+ regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two
+ digit hex encoding. The message ID is a valid Xapian query,
+ quoted using Xapian boolean term quoting rules: if the ID
+ contains whitespace or a close paren or starts with a double
+ quote, it must be enclosed in double quotes and double quotes
+ inside the ID must be doubled. The astute reader will notice
+ this is a special case of the batch input format for
+ **notmuch-tag(1)**; note that the single message-id query is
+ mandatory for **notmuch-restore(1)**.
+
+ **sup**
+ The **sup** dump file format is specifically chosen to be
+ compatible with the format of files produced by sup-dump. So
+ if you've previously been using sup for mail, then the
+ **notmuch restore** command provides you a way to import all
+ of your tags (or labels as sup calls them). Each line has the
+ following form::
+
+ <*message-id*\ > **(** <*tag*\ > ... **)**
+
+ with zero or more tags are separated by spaces. Note that
+ (malformed) message-ids may contain arbitrary non-null
+ characters. Note also that tags with spaces will not be
+ correctly restored with this format.
+
+``--include=(config|properties|tags)``
Control what kind of metadata is included in the output.
- **config**
-
+ **config**
Output configuration data stored in the database. Each line
starts with "#@ ", followed by a space separated key-value
pair. Both key and value are hex encoded if needed.
- **properties**
-
+ **properties**
Output per-message (key,value) metadata. Each line starts
with "#= ", followed by a message id, and a space separated
list of key=value pairs. Ids, keys and values are hex encoded
if needed. See **notmuch-properties(7)** for more details.
- **tags**
-
+ **tags**
Output per-message boolean metadata, namely tags. See *format* above
for description of the output.
- The default is to include all available types of data. The
- option can be specified multiple times to select some subset. As
- of version 3 of the dump format, there is a header line of the
- following form
+ The default is to include all available types of data. The option
+ can be specified multiple times to select some subset. As of
+ version 3 of the dump format, there is a header line of the
+ following form::
- |
- | #notmuch-dump <*format*>:<*version*> <*included*>
+ #notmuch-dump <*format*>:<*version*> <*included*>
- where <*included*> is a comma separated list of the above
- options.
+ where <*included*> is a comma separated list of the above options.
- ``--output=``\ <filename>
- Write output to given file instead of stdout.
+``--output=``\ <filename>
+ Write output to given file instead of stdout.
SEE ALSO
========
Supported options for **emacs-mua** include
- ``-h, --help``
- Display help.
+``-h, --help``
+ Display help.
- ``-s, --subject=``\ <subject>
- Specify the subject of the message.
+``-s, --subject=``\ <subject>
+ Specify the subject of the message.
- ``--to=``\ <to-address>
- Specify a recipient (To).
+``--to=``\ <to-address>
+ Specify a recipient (To).
- ``-c, --cc=``\ <cc-address>
- Specify a carbon-copy (Cc) recipient.
+``-c, --cc=``\ <cc-address>
+ Specify a carbon-copy (Cc) recipient.
- ``-b, --bcc=``\ <bcc-address>
- Specify a blind-carbon-copy (Bcc) recipient.
+``-b, --bcc=``\ <bcc-address>
+ Specify a blind-carbon-copy (Bcc) recipient.
- ``-i, --body=``\ <file>
- Specify a file to include into the body of the message.
+``-i, --body=``\ <file>
+ Specify a file to include into the body of the message.
- ``--hello``
- Go to the Notmuch hello screen instead of the message composition
- window if no message composition parameters are given.
+``--hello``
+ Go to the Notmuch hello screen instead of the message composition
+ window if no message composition parameters are given.
- ``--no-window-system``
- Even if a window system is available, use the current terminal.
+``--no-window-system``
+ Even if a window system is available, use the current terminal.
- ``--client``
- Use **emacsclient**, rather than **emacs**. For
- **emacsclient** to work, you need an already running Emacs
- with a server, or use ``--auto-daemon``.
+``--client``
+ Use **emacsclient**, rather than **emacs**. For **emacsclient** to
+ work, you need an already running Emacs with a server, or use
+ ``--auto-daemon``.
- ``--auto-daemon``
- Automatically start Emacs in daemon mode, if the Emacs server
- is not running. Applicable with ``--client``. Implies
- ``--create-frame``.
+``--auto-daemon``
+ Automatically start Emacs in daemon mode, if the Emacs server is
+ not running. Applicable with ``--client``. Implies
+ ``--create-frame``.
- ``--create-frame``
- Create a new frame instead of trying to use the current Emacs
- frame. Applicable with ``--client``. This will be required
- when Emacs is running (or automatically started with
- ``--auto-daemon``) in daemon mode.
+``--create-frame``
+ Create a new frame instead of trying to use the current Emacs
+ frame. Applicable with ``--client``. This will be required when
+ Emacs is running (or automatically started with ``--auto-daemon``)
+ in daemon mode.
- ``--print``
- Output the resulting elisp to stdout instead of evaluating it.
+``--print``
+ Output the resulting elisp to stdout instead of evaluating it.
The supported positional parameters and short options are a compatible
subset of the **mutt** MUA command-line options. The options and
Option arguments must appear before any tag operation arguments.
Supported options for **insert** include
- ``--folder=<``\ folder\ **>**
- Deliver the message to the specified folder, relative to the
- top-level directory given by the value of **database.path**. The
- default is the empty string, which means delivering to the
- top-level directory.
-
- ``--create-folder``
- Try to create the folder named by the ``--folder`` option, if it
- does not exist. Otherwise the folder must already exist for mail
- delivery to succeed.
-
- ``--keep``
- Keep the message file if indexing fails, and keep the message
- indexed if applying tags or maildir flag synchronization
- fails. Ignore these errors and return exit status 0 to
- indicate successful mail delivery.
-
- ``--no-hooks``
- Prevent hooks from being run.
-
- ``--decrypt=(true|nostash|auto|false)``
-
- If ``true`` and the message is encrypted, try to decrypt the
- message while indexing, stashing any session keys discovered.
- If ``auto``, and notmuch already knows about a session key for
- the message, it will try decrypting using that session key but
- will not try to access the user's secret keys. If decryption
- is successful, index the cleartext itself. Either way, the
- message is always stored to disk in its original form
- (ciphertext).
-
- ``nostash`` is the same as ``true`` except that it will not
- stash newly-discovered session keys in the database.
-
- Be aware that the 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
- ``--decrypt=true`` or ``--decrypt=nostash`` without
- considering the security of your index.
-
- See also ``index.decrypt`` in **notmuch-config(1)**.
+``--folder=<``\ folder\ **>**
+ Deliver the message to the specified folder, relative to the
+ top-level directory given by the value of **database.path**. The
+ default is the empty string, which means delivering to the
+ top-level directory.
+
+``--create-folder``
+ Try to create the folder named by the ``--folder`` option, if it
+ does not exist. Otherwise the folder must already exist for mail
+ delivery to succeed.
+
+``--keep``
+ Keep the message file if indexing fails, and keep the message
+ indexed if applying tags or maildir flag synchronization
+ fails. Ignore these errors and return exit status 0 to indicate
+ successful mail delivery.
+
+``--no-hooks``
+ Prevent hooks from being run.
+
+``--world-readable``
+ When writing mail to the mailbox, allow it to be read by users
+ other than the current user. Note that this does not override
+ umask. By default, delivered mail is only readable by the current
+ user.
+
+``--decrypt=(true|nostash|auto|false)``
+ If ``true`` and the message is encrypted, try to decrypt the
+ message while indexing, stashing any session keys discovered. If
+ ``auto``, and notmuch already knows about a session key for the
+ message, it will try decrypting using that session key but will
+ not try to access the user's secret keys. If decryption is
+ successful, index the cleartext itself. Either way, the message
+ is always stored to disk in its original form (ciphertext).
+
+ ``nostash`` is the same as ``true`` except that it will not stash
+ newly-discovered session keys in the database.
+
+ Be aware that the 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 ``--decrypt=true`` or
+ ``--decrypt=nostash`` without considering the security of your
+ index.
+
+ See also ``index.decrypt`` in **notmuch-config(1)**.
EXIT STATUS
===========
Supported options for **new** include
- ``--no-hooks``
- Prevents hooks from being run.
-
- ``--quiet``
- Do not print progress or results.
-
- ``--decrypt=(true|nostash|auto|false)``
-
- If ``true``, when encountering an encrypted message, try to
- decrypt it while indexing, and stash any discovered session
- keys. If ``auto``, try to use any session key already known
- to belong to this message, but do not attempt to use the
- user's secret keys. If decryption is successful, index the
- cleartext of the message.
-
- Be aware that the index is likely sufficient (and the 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 ``--decrypt=true``
- or ``--decrypt=nostash`` without considering the security of
- your index.
-
- See also ``index.decrypt`` in **notmuch-config(1)**.
+``--no-hooks``
+ Prevents hooks from being run.
+
+``--quiet``
+ Do not print progress or results.
+
+``--decrypt=(true|nostash|auto|false)``
+ If ``true``, when encountering an encrypted message, try to
+ decrypt it while indexing, and stash any discovered session keys.
+ If ``auto``, try to use any session key already known to belong to
+ this message, but do not attempt to use the user's secret keys.
+ If decryption is successful, index the cleartext of the message.
+
+ Be aware that the index is likely sufficient (and the 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 ``--decrypt=true`` or
+ ``--decrypt=nostash`` without considering the security of your
+ index.
+
+ See also ``index.decrypt`` in **notmuch-config(1)**.
EXIT STATUS
===========
Supported options for **reindex** include
- ``--decrypt=(true|nostash|auto|false)``
+``--decrypt=(true|nostash|auto|false)``
+ If ``true``, when encountering an encrypted message, try to
+ decrypt it while reindexing, stashing any session keys discovered.
+ If ``auto``, and notmuch already knows about a session key for the
+ message, it will try decrypting using that session key but will
+ not try to access the user's secret keys. If decryption is
+ successful, index the cleartext itself.
- If ``true``, when encountering an encrypted message, try to
- decrypt it while reindexing, stashing any session keys
- discovered. If ``auto``, and notmuch already knows about a
- session key for the message, it will try decrypting using that
- session key but will not try to access the user's secret keys.
- If decryption is successful, index the cleartext itself.
+ ``nostash`` is the same as ``true`` except that it will not stash
+ newly-discovered session keys in the database.
- ``nostash`` is the same as ``true`` except that it will not
- stash newly-discovered session keys in the database.
+ If ``false``, notmuch reindex will also delete any stashed session
+ keys for all messages matching the search terms.
- If ``false``, notmuch reindex will also delete any stashed
- session keys for all messages matching the search terms.
+ Be aware that the 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 ``--decrypt=true`` or
+ ``--decrypt=nostash`` without considering the security of your
+ index.
- Be aware that the 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
- ``--decrypt=true`` or ``--decrypt=nostash`` without
- considering the security of your index.
+ See also ``index.decrypt`` in **notmuch-config(1)**.
- See also ``index.decrypt`` in **notmuch-config(1)**.
+EXAMPLES
+========
+
+A user just received an encrypted message without indexing its
+cleartext. After reading it (via ``notmuch show --decrypt=true``),
+they decide that they want to index its cleartext so that they can
+easily find it later and read it without having to have access to
+their secret keys:
+
+::
+
+ notmuch reindex --decrypt=true id:1234567@example.com
+
+A user wants to change their policy going forward to start indexing
+cleartext. But they also want indexed access to the cleartext of all
+previously-received encrypted messages. Some messages might have
+already been indexed in the clear (as in the example above). They can
+ask notmuch to just reindex the not-yet-indexed messages:
+
+::
+
+ notmuch config set index.decrypt true
+ notmuch reindex tag:encrypted and not property:index.decryption=success
+
+Later, the user changes their mind, and wants to stop indexing
+cleartext (perhaps their threat model has changed, or their trust in
+their index store has been shaken). They also want to clear all of
+their old cleartext from the index. Note that they compact the
+database afterward as a workaround for
+https://trac.xapian.org/ticket/742:
+
+::
+
+ notmuch config set index.decrypt false
+ notmuch reindex property:index.decryption=success
+ notmuch compact
SEE ALSO
========
**notmuch(1)**,
+**notmuch-compact(1)**,
**notmuch-config(1)**,
**notmuch-count(1)**,
**notmuch-dump(1)**,
Supported options for **reply** include
- ``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
-
- **default**
- Includes subject and quoted message body as an RFC 2822
- message.
-
- **json**
- Produces JSON output containing headers for a reply message
- and the contents of the original message. This output can be
- used by a client to create a reply message intelligently.
-
- **sexp**
- Produces S-Expression output containing headers for a reply
- message and the contents of the original message. This
- output can be used by a client to create a reply message
- intelligently.
-
- **headers-only**
- Only produces In-Reply-To, References, To, Cc, and Bcc
- headers.
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- omitted, the latest supported version will be used.
-
- ``--reply-to=``\ (**all**\ \|\ **sender**)
-
- **all** (default)
- Replies to all addresses.
-
- **sender**
- Replies only to the sender. If replying to user's own
- message (Reply-to: or From: header is one of the user's
- configured email addresses), try To:, Cc:, and Bcc: headers
- in this order, and copy values from the first that contains
- something other than only the user's addresses.
-
- ``--decrypt=(false|auto|true)``
-
- If ``true``, decrypt any MIME encrypted parts found in the
- selected content (i.e., "multipart/encrypted" parts). Status
- of the decryption will be reported (currently only supported
- with --format=json and --format=sexp), and on successful
- decryption the multipart/encrypted part will be replaced by
- the decrypted content.
-
- If ``auto``, and a session key is already known for the
- message, then it will be decrypted, but notmuch will not try
- to access the user's secret keys.
-
- Use ``false`` to avoid even automatic decryption.
-
- Non-automatic decryption expects a functioning
- **gpg-agent(1)** to provide any needed credentials. Without
- one, the decryption will likely fail.
-
- Default: ``auto``
+``--format=``\ (**default**\ \|\ **json**\ \|\ **sexp**\ \|\ **headers-only**)
+ **default**
+ Includes subject and quoted message body as an RFC 2822
+ message.
+
+ **json**
+ Produces JSON output containing headers for a reply message
+ and the contents of the original message. This output can be
+ used by a client to create a reply message intelligently.
+
+ **sexp**
+ Produces S-Expression output containing headers for a reply
+ message and the contents of the original message. This output
+ can be used by a client to create a reply message
+ intelligently.
+
+ **headers-only**
+ Only produces In-Reply-To, References, To, Cc, and Bcc
+ headers.
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ omitted, the latest supported version will be used.
+
+``--reply-to=``\ (**all**\ \|\ **sender**)
+ **all** (default)
+ Replies to all addresses.
+
+ **sender**
+ Replies only to the sender. If replying to user's own message
+ (Reply-to: or From: header is one of the user's configured
+ email addresses), try To:, Cc:, and Bcc: headers in this
+ order, and copy values from the first that contains something
+ other than only the user's addresses.
+
+``--decrypt=(false|auto|true)``
+
+ If ``true``, decrypt any MIME encrypted parts found in the
+ selected content (i.e., "multipart/encrypted" parts). Status
+ of the decryption will be reported (currently only supported
+ with --format=json and --format=sexp), and on successful
+ decryption the multipart/encrypted part will be replaced by
+ the decrypted content.
+
+ If ``auto``, and a session key is already known for the
+ message, then it will be decrypted, but notmuch will not try
+ to access the user's secret keys.
+
+ Use ``false`` to avoid even automatic decryption.
+
+ Non-automatic decryption expects a functioning
+ **gpg-agent(1)** to provide any needed credentials. Without
+ one, the decryption will likely fail.
+
+ Default: ``auto``
See **notmuch-search-terms(7)** for details of the supported syntax for
<search-terms>.
Supported options for **restore** include
- ``--accumulate``
- The union of the existing and new tags is applied, instead of
- replacing each message's tags as they are read in from the dump
- file.
-
- ``--format=(sup|batch-tag|auto)``
- Notmuch restore supports two plain text dump formats, with each
- line specifying a message-id and a set of tags. For details of
- the actual formats, see **notmuch-dump(1)**.
-
- **sup**
- The **sup** dump file format is specifically chosen to be
- compatible with the format of files produced by sup-dump. So
- if you've previously been using sup for mail, then the
- **notmuch restore** command provides you a way to import all
- of your tags (or labels as sup calls them).
-
- **batch-tag**
- The **batch-tag** dump format is intended to more robust
- against malformed message-ids and tags containing whitespace
- or non-\ **ascii(7)** characters. See **notmuch-dump(1)**
- for details on this format.
-
- **notmuch restore** updates the maildir flags according to
- tag changes if the **maildir.synchronize\_flags**
- configuration option is enabled. See **notmuch-config(1)**
- for details.
-
- **auto**
- This option (the default) tries to guess the format from the
- input. For correctly formed input in either supported
- format, this heuristic, based the fact that batch-tag format
- contains no parentheses, should be accurate.
-
- ``--include=(config|properties|tags)``
-
- Control what kind of metadata is restored.
-
- **config**
-
- Restore configuration data to the database. Each configuration line starts
- with "#@ ", followed by a space separated key-value pair.
- Both key and value are hex encoded if needed.
-
- **properties**
-
- Restore per-message (key,value) metadata. Each line starts
- with "#= ", followed by a message id, and a space separated
- list of key=value pairs. Ids, keys and values are hex
- encoded if needed. See **notmuch-properties(7)** for more
- details.
-
- **tags**
-
- Restore per-message metadata, namely tags. See *format* above
- for more details.
-
- The default is to restore all available types of data. The
- option can be specified multiple times to select some subset.
-
- ``--input=``\ <filename>
- Read input from given file instead of stdin.
+``--accumulate``
+ The union of the existing and new tags is applied, instead of
+ replacing each message's tags as they are read in from the dump
+ file.
+
+``--format=(sup|batch-tag|auto)``
+ Notmuch restore supports two plain text dump formats, with each
+ line specifying a message-id and a set of tags. For details of the
+ actual formats, see **notmuch-dump(1)**.
+
+ **sup**
+ The **sup** dump file format is specifically chosen to be
+ compatible with the format of files produced by sup-dump. So
+ if you've previously been using sup for mail, then the
+ **notmuch restore** command provides you a way to import all
+ of your tags (or labels as sup calls them).
+
+ **batch-tag**
+ The **batch-tag** dump format is intended to more robust
+ against malformed message-ids and tags containing whitespace
+ or non-\ **ascii(7)** characters. See **notmuch-dump(1)** for
+ details on this format.
+
+ **notmuch restore** updates the maildir flags according to tag
+ changes if the **maildir.synchronize\_flags** configuration
+ option is enabled. See **notmuch-config(1)** for details.
+
+ **auto**
+ This option (the default) tries to guess the format from the
+ input. For correctly formed input in either supported format,
+ this heuristic, based the fact that batch-tag format contains
+ no parentheses, should be accurate.
+
+``--include=(config|properties|tags)``
+ Control what kind of metadata is restored.
+
+ **config**
+ Restore configuration data to the database. Each configuration
+ line starts with "#@ ", followed by a space separated
+ key-value pair. Both key and value are hex encoded if needed.
+
+ **properties**
+ Restore per-message (key,value) metadata. Each line starts
+ with "#= ", followed by a message id, and a space separated
+ list of key=value pairs. Ids, keys and values are hex encoded
+ if needed. See **notmuch-properties(7)** for more details.
+
+ **tags**
+ Restore per-message metadata, namely tags. See *format* above
+ for more details.
+
+ The default is to restore all available types of data. The option
+ can be specified multiple times to select some subset.
+
+``--input=``\ <filename>
+ Read input from given file instead of stdin.
GZIPPED INPUT
=============
Supported options for **search** include
- ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
- Presents the results in either JSON, S-Expressions, newline
- character separated plain-text (default), or null character
- separated plain-text (compatible with **xargs(1)** -0 option
- where available).
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- omitted, the latest supported version will be used.
-
- ``--output=(summary|threads|messages|files|tags)``
-
- **summary**
- Output a summary of each thread with any message matching
- the search terms. The summary includes the thread ID, date,
- the number of messages in the thread (both the number
- matched and the total number), the authors of the thread and
- the subject. In the case where a thread contains multiple files for
- some messages, the total number of files is printed in parentheses
- (see below for an example).
-
- **threads**
- Output the thread IDs of all threads with any message
- matching the search terms, either one per line
- (--format=text), separated by null characters
- (--format=text0), as a JSON array (--format=json), or an
- S-Expression list (--format=sexp).
-
- **messages**
- Output the message IDs of all messages matching the search
- terms, either one per line (--format=text), separated by
- null characters (--format=text0), as a JSON array
- (--format=json), or as an S-Expression list (--format=sexp).
-
- **files**
- Output the filenames of all messages matching the search
- terms, either one per line (--format=text), separated by
- null characters (--format=text0), as a JSON array
- (--format=json), or as an S-Expression list (--format=sexp).
-
- Note that each message may have multiple filenames
- associated with it. All of them are included in the output
- (unless limited with the --duplicate=N option). This may
- be particularly confusing for **folder:** or **path:**
- searches in a specified directory, as the messages may
- have duplicates in other directories that are included in
- the output, although these files alone would not match the
- search.
-
- **tags**
- Output all tags that appear on any message matching the
- search terms, either one per line (--format=text), separated
- by null characters (--format=text0), as a JSON array
- (--format=json), or as an S-Expression list (--format=sexp).
-
- ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
- This option can be used to present results in either
- chronological order (**oldest-first**) or reverse chronological
- order (**newest-first**).
-
- Note: The thread order will be distinct between these two
- options (beyond being simply reversed). When sorting by
- **oldest-first** the threads will be sorted by the oldest
- message in each thread, but when sorting by **newest-first** the
- threads will be sorted by the newest message in each thread.
-
- By default, results will be displayed in reverse chronological
- order, (that is, the newest results will be displayed first).
-
- ``--offset=[-]N``
- Skip displaying the first N results. With the leading '-', start
- at the Nth result from the end.
-
- ``--limit=N``
- Limit the number of displayed results to N.
-
- ``--exclude=(true|false|all|flag)``
- A message is called "excluded" if it matches at least one tag in
- search.tag\_exclude that does not appear explicitly in the
- search terms. This option specifies whether to omit excluded
- messages in the search process.
-
- The default value, **true**, prevents excluded messages from
- matching the search terms.
-
- **all** additionally prevents excluded messages from appearing
- in displayed results, in effect behaving as though the excluded
+``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
+ Presents the results in either JSON, S-Expressions, newline
+ character separated plain-text (default), or null character
+ separated plain-text (compatible with **xargs(1)** -0 option where
+ available).
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ omitted, the latest supported version will be used.
+
+``--output=(summary|threads|messages|files|tags)``
+ **summary**
+ Output a summary of each thread with any message matching the
+ search terms. The summary includes the thread ID, date, the
+ number of messages in the thread (both the number matched and
+ the total number), the authors of the thread and the
+ subject. In the case where a thread contains multiple files
+ for some messages, the total number of files is printed in
+ parentheses (see below for an example).
+
+ **threads**
+ Output the thread IDs of all threads with any message matching
+ the search terms, either one per line (--format=text),
+ separated by null characters (--format=text0), as a JSON array
+ (--format=json), or an S-Expression list (--format=sexp).
+
+ **messages**
+ Output the message IDs of all messages matching the search
+ terms, either one per line (--format=text), separated by null
+ characters (--format=text0), as a JSON array (--format=json),
+ or as an S-Expression list (--format=sexp).
+
+ **files**
+ Output the filenames of all messages matching the search
+ terms, either one per line (--format=text), separated by null
+ characters (--format=text0), as a JSON array (--format=json),
+ or as an S-Expression list (--format=sexp).
+
+ Note that each message may have multiple filenames associated
+ with it. All of them are included in the output (unless
+ limited with the --duplicate=N option). This may be
+ particularly confusing for **folder:** or **path:** searches
+ in a specified directory, as the messages may have duplicates
+ in other directories that are included in the output, although
+ these files alone would not match the search.
+
+ **tags**
+ Output all tags that appear on any message matching the search
+ terms, either one per line (--format=text), separated by null
+ characters (--format=text0), as a JSON array (--format=json),
+ or as an S-Expression list (--format=sexp).
+
+``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
+ This option can be used to present results in either chronological
+ order (**oldest-first**) or reverse chronological order
+ (**newest-first**).
+
+ Note: The thread order will be distinct between these two options
+ (beyond being simply reversed). When sorting by **oldest-first**
+ the threads will be sorted by the oldest message in each thread,
+ but when sorting by **newest-first** the threads will be sorted by
+ the newest message in each thread.
+
+ By default, results will be displayed in reverse chronological
+ order, (that is, the newest results will be displayed first).
+
+``--offset=[-]N``
+ Skip displaying the first N results. With the leading '-', start
+ at the Nth result from the end.
+
+``--limit=N``
+ Limit the number of displayed results to N.
+
+``--exclude=(true|false|all|flag)``
+ A message is called "excluded" if it matches at least one tag in
+ search.tag\_exclude that does not appear explicitly in the search
+ terms. This option specifies whether to omit excluded messages in
+ the search process.
+
+ **true** (default)
+ Prevent excluded messages from matching the search terms.
+
+ **all**
+ Additionally prevent excluded messages from appearing in
+ displayed results, in effect behaving as though the excluded
messages do not exist.
- **false** allows excluded messages to match search terms and
- appear in displayed results. Excluded messages are still marked
- in the relevant outputs.
-
- **flag** only has an effect when ``--output=summary``. The
- output is almost identical to **false**, but the "match count"
- is the number of matching non-excluded messages in the thread,
- rather than the number of matching messages.
-
- ``--duplicate=N``
- For ``--output=files``, output the Nth filename associated
- with each message matching the query (N is 1-based). If N is
- greater than the number of files associated with the message,
- don't print anything.
-
- For ``--output=messages``, only output message IDs of messages
- matching the search terms that have at least N filenames
- associated with them.
-
- Note that this option is orthogonal with the **folder:** search
- prefix. The prefix matches messages based on filenames. This
- option filters filenames of the matching messages.
+ **false**
+ Allow excluded messages to match search terms and appear in
+ displayed results. Excluded messages are still marked in the
+ relevant outputs.
+
+ **flag**
+ Only has an effect when ``--output=summary``. The output is
+ almost identical to **false**, but the "match count" is the
+ number of matching non-excluded messages in the thread, rather
+ than the number of matching messages.
+
+``--duplicate=N``
+ For ``--output=files``, output the Nth filename associated with
+ each message matching the query (N is 1-based). If N is greater
+ than the number of files associated with the message, don't print
+ anything.
+
+ For ``--output=messages``, only output message IDs of messages
+ matching the search terms that have at least N filenames
+ associated with them.
+
+ Note that this option is orthogonal with the **folder:** search
+ prefix. The prefix matches messages based on filenames. This
+ option filters filenames of the matching messages.
EXAMPLE
=======
Supported options for **show** include
- ``--entire-thread=(true|false)``
- If true, **notmuch show** outputs all messages in the thread of
- any message matching the search terms; if false, it outputs only
- the matching messages. For ``--format=json`` and
- ``--format=sexp`` this defaults to true. For other formats, this
- defaults to false.
-
- ``--format=(text|json|sexp|mbox|raw)``
-
- **text** (default for messages)
- The default plain-text format has all text-content MIME
- parts decoded. Various components in the output,
- (**message**, **header**, **body**, **attachment**, and MIME
- **part**), will be delimited by easily-parsed markers. Each
- marker consists of a Control-L character (ASCII decimal 12),
- the name of the marker, and then either an opening or
- closing brace, ('{' or '}'), to either open or close the
- component. For a multipart MIME message, these parts will be
- nested.
-
- **json**
- The output is formatted with Javascript Object Notation
- (JSON). This format is more robust than the text format for
- automated processing. The nested structure of multipart MIME
- messages is reflected in nested JSON output. By default JSON
- output includes all messages in a matching thread; that is,
- by default,
- ``--format=json`` sets ``--entire-thread``. The caller can
- disable this behaviour by setting ``--entire-thread=false``.
- The JSON output is always encoded as UTF-8 and any message
- content included in the output will be charset-converted to
- UTF-8.
-
- **sexp**
- The output is formatted as the Lisp s-expression (sexp)
- equivalent of the JSON format above. Objects are formatted
- as property lists whose keys are keywords (symbols preceded
- by a colon). True is formatted as ``t`` and both false and
- null are formatted as ``nil``. As for JSON, the s-expression
- output is always encoded as UTF-8.
-
- **mbox**
- All matching messages are output in the traditional, Unix
- mbox format with each message being prefixed by a line
- beginning with "From " and a blank line separating each
- message. Lines in the message content beginning with "From "
- (preceded by zero or more '>' characters) have an additional
- '>' character added. This reversible escaping is termed
- "mboxrd" format and described in detail here:
+``--entire-thread=(true|false)``
+ If true, **notmuch show** outputs all messages in the thread of
+ any message matching the search terms; if false, it outputs only
+ the matching messages. For ``--format=json`` and ``--format=sexp``
+ this defaults to true. For other formats, this defaults to false.
+
+``--format=(text|json|sexp|mbox|raw)``
+ **text** (default for messages)
+ The default plain-text format has all text-content MIME parts
+ decoded. Various components in the output, (**message**,
+ **header**, **body**, **attachment**, and MIME **part**), will
+ be delimited by easily-parsed markers. Each marker consists of
+ a Control-L character (ASCII decimal 12), the name of the
+ marker, and then either an opening or closing brace, ('{' or
+ '}'), to either open or close the component. For a multipart
+ MIME message, these parts will be nested.
+
+ **json**
+ The output is formatted with Javascript Object Notation
+ (JSON). This format is more robust than the text format for
+ automated processing. The nested structure of multipart MIME
+ messages is reflected in nested JSON output. By default JSON
+ output includes all messages in a matching thread; that is, by
+ default, ``--format=json`` sets ``--entire-thread``. The
+ caller can disable this behaviour by setting
+ ``--entire-thread=false``. The JSON output is always encoded
+ as UTF-8 and any message content included in the output will
+ be charset-converted to UTF-8.
+
+ **sexp**
+ The output is formatted as the Lisp s-expression (sexp)
+ equivalent of the JSON format above. Objects are formatted as
+ property lists whose keys are keywords (symbols preceded by a
+ colon). True is formatted as ``t`` and both false and null are
+ formatted as ``nil``. As for JSON, the s-expression output is
+ always encoded as UTF-8.
+
+ **mbox**
+ All matching messages are output in the traditional, Unix mbox
+ format with each message being prefixed by a line beginning
+ with "From " and a blank line separating each message. Lines
+ in the message content beginning with "From " (preceded by
+ zero or more '>' characters) have an additional '>' character
+ added. This reversible escaping is termed "mboxrd" format and
+ described in detail here:
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
- **raw** (default if --part is given)
- Write the raw bytes of the given MIME part of a message to
- standard out. For this format, it is an error to specify a
- query that matches more than one message.
-
- If the specified part is a leaf part, this outputs the
- body of the part after performing content transfer
- decoding (but no charset conversion). This is suitable for
- saving attachments, for example.
-
- For a multipart or message part, the output includes the
- part headers as well as the body (including all child
- parts). No decoding is performed because multipart and
- message parts cannot have non-trivial content transfer
- encoding. Consumers of this may need to implement MIME
- decoding and similar functions.
-
- ``--format-version=N``
- Use the specified structured output format version. This is
- intended for programs that invoke **notmuch(1)** internally. If
- omitted, the latest supported version will be used.
-
- ``--part=N``
- Output the single decoded MIME part N of a single message. The
- search terms must match only a single message. Message parts are
- numbered in a depth-first walk of the message MIME structure,
- and are identified in the 'json', 'sexp' or 'text' output
- formats.
-
- Note that even a message with no MIME structure or a single
- body part still has two MIME parts: part 0 is the whole
- message (headers and body) and part 1 is just the body.
-
- ``--verify``
- Compute and report the validity of any MIME cryptographic
- signatures found in the selected content (ie. "multipart/signed"
- parts). Status of the signature will be reported (currently only
- supported with --format=json and --format=sexp), and the
- multipart/signed part will be replaced by the signed data.
-
- ``--decrypt=(false|auto|true)``
- If ``true``, decrypt any MIME encrypted parts found in the
- selected content (i.e. "multipart/encrypted" parts). Status of
- the decryption will be reported (currently only supported
- with --format=json and --format=sexp) and on successful
- decryption the multipart/encrypted part will be replaced by
- the decrypted content.
-
- If ``auto``, and a session key is already known for the
- message, then it will be decrypted, but notmuch will not try
- to access the user's keys.
-
- Use ``false`` to avoid even automatic decryption.
-
- Non-automatic decryption expects a functioning
- **gpg-agent(1)** to provide any needed credentials. Without
- one, the decryption will fail.
-
- Note: ``true`` implies --verify.
-
- Default: ``auto``
-
- ``--exclude=(true|false)``
- Specify whether to omit threads only matching
- search.tag\_exclude from the search results (the default) or
- not. In either case the excluded message will be marked with the
- exclude flag (except when output=mbox when there is nowhere to
- put the flag).
-
- If --entire-thread is specified then complete threads are
- returned regardless (with the excluded flag being set when
- appropriate) but threads that only match in an excluded message
- are not returned when ``--exclude=true.``
-
- The default is ``--exclude=true.``
-
- ``--body=(true|false)``
- If true (the default) **notmuch show** includes the bodies of
- the messages in the output; if false, bodies are omitted.
- ``--body=false`` is only implemented for the json and sexp
- formats and it is incompatible with ``--part > 0.``
-
- This is useful if the caller only needs the headers as body-less
- output is much faster and substantially smaller.
-
- ``--include-html``
- Include "text/html" parts as part of the output (currently only
- supported with --format=json and --format=sexp). By default,
- unless ``--part=N`` is used to select a specific part or
- ``--include-html`` is used to include all "text/html" parts, no
- part with content type "text/html" is included in the output.
+ **raw** (default if --part is given)
+ Write the raw bytes of the given MIME part of a message to
+ standard out. For this format, it is an error to specify a
+ query that matches more than one message.
+
+ If the specified part is a leaf part, this outputs the body of
+ the part after performing content transfer decoding (but no
+ charset conversion). This is suitable for saving attachments,
+ for example.
+
+ For a multipart or message part, the output includes the part
+ headers as well as the body (including all child parts). No
+ decoding is performed because multipart and message parts
+ cannot have non-trivial content transfer encoding. Consumers
+ of this may need to implement MIME decoding and similar
+ functions.
+
+``--format-version=N``
+ Use the specified structured output format version. This is
+ intended for programs that invoke **notmuch(1)** internally. If
+ omitted, the latest supported version will be used.
+
+``--part=N``
+ Output the single decoded MIME part N of a single message. The
+ search terms must match only a single message. Message parts are
+ numbered in a depth-first walk of the message MIME structure, and
+ are identified in the 'json', 'sexp' or 'text' output formats.
+
+ Note that even a message with no MIME structure or a single body
+ part still has two MIME parts: part 0 is the whole message
+ (headers and body) and part 1 is just the body.
+
+``--verify``
+ Compute and report the validity of any MIME cryptographic
+ signatures found in the selected content (ie. "multipart/signed"
+ parts). Status of the signature will be reported (currently only
+ supported with --format=json and --format=sexp), and the
+ multipart/signed part will be replaced by the signed data.
+
+``--decrypt=(false|auto|true)``
+ If ``true``, decrypt any MIME encrypted parts found in the
+ selected content (i.e. "multipart/encrypted" parts). Status of
+ the decryption will be reported (currently only supported
+ with --format=json and --format=sexp) and on successful
+ decryption the multipart/encrypted part will be replaced by
+ the decrypted content.
+
+ If ``auto``, and a session key is already known for the
+ message, then it will be decrypted, but notmuch will not try
+ to access the user's keys.
+
+ Use ``false`` to avoid even automatic decryption.
+
+ Non-automatic decryption expects a functioning
+ **gpg-agent(1)** to provide any needed credentials. Without
+ one, the decryption will fail.
+
+ Note: ``true`` implies --verify.
+
+ Default: ``auto``
+
+``--exclude=(true|false)``
+ Specify whether to omit threads only matching search.tag\_exclude
+ from the search results (the default) or not. In either case the
+ excluded message will be marked with the exclude flag (except when
+ output=mbox when there is nowhere to put the flag).
+
+ If --entire-thread is specified then complete threads are returned
+ regardless (with the excluded flag being set when appropriate) but
+ threads that only match in an excluded message are not returned
+ when ``--exclude=true.``
+
+ The default is ``--exclude=true.``
+
+``--body=(true|false)``
+ If true (the default) **notmuch show** includes the bodies of the
+ messages in the output; if false, bodies are omitted.
+ ``--body=false`` is only implemented for the json and sexp formats
+ and it is incompatible with ``--part > 0.``
+
+ This is useful if the caller only needs the headers as body-less
+ output is much faster and substantially smaller.
+
+``--include-html``
+ Include "text/html" parts as part of the output (currently only
+ supported with --format=json and --format=sexp). By default,
+ unless ``--part=N`` is used to select a specific part or
+ ``--include-html`` is used to include all "text/html" parts, no
+ part with content type "text/html" is included in the output.
A common use of **notmuch show** is to display a single thread of email
messages. For this, use a search term of "thread:<thread-id>" as can be
Supported options for **tag** include
- ``--remove-all``
- Remove all tags from each message matching the search terms
- before applying the tag changes appearing on the command line.
- This means setting the tags of each message to the tags to be
- added. If there are no tags to be added, the messages will have
- no tags.
-
- ``--batch``
- Read batch tagging operations from a file (stdin by default).
- This is more efficient than repeated **notmuch tag**
- invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below
- for the input format. This option is not compatible with
- specifying tagging on the command line.
-
- ``--input=``\ <filename>
- Read input from given file, instead of from stdin. Implies
- ``--batch``.
+``--remove-all``
+ Remove all tags from each message matching the search terms before
+ applying the tag changes appearing on the command line. This
+ means setting the tags of each message to the tags to be added. If
+ there are no tags to be added, the messages will have no tags.
+
+``--batch``
+ Read batch tagging operations from a file (stdin by default).
+ This is more efficient than repeated **notmuch tag**
+ invocations. See `TAG FILE FORMAT <#tag_file_format>`__ below for
+ the input format. This option is not compatible with specifying
+ tagging on the command line.
+
+``--input=``\ <filename>
+ Read input from given file, instead of from stdin. Implies
+ ``--batch``.
TAG FILE FORMAT
===============
Supported global options for ``notmuch`` include
- ``--help`` [command-name]
- Print a synopsis of available commands and exit.
- With an optional command name, show the man page
- for that subcommand.
+``--help`` [command-name]
+ Print a synopsis of available commands and exit. With an optional
+ command name, show the man page for that subcommand.
- ``--version``
- Print the installed version of notmuch, and exit.
+``--version``
+ Print the installed version of notmuch, and exit.
- ``--config=FILE``
- Specify the configuration file to use. This overrides any
- configuration file specified by ${NOTMUCH\_CONFIG}.
+``--config=FILE``
+ Specify the configuration file to use. This overrides any
+ configuration file specified by ${NOTMUCH\_CONFIG}.
- ``--uuid=HEX``
- Enforce that the database UUID (a unique identifier which
- persists until e.g. the database is compacted)
- is HEX; exit with an error if it is not. This is useful to
- detect rollover in modification counts on messages. You can
- find this UUID using e.g. ``notmuch count --lastmod``
+``--uuid=HEX``
+ Enforce that the database UUID (a unique identifier which persists
+ until e.g. the database is compacted) is HEX; exit with an error
+ if it is not. This is useful to detect rollover in modification
+ counts on messages. You can find this UUID using e.g. ``notmuch
+ count --lastmod``
All global options except ``--config`` can also be specified after the
-command. For example, ``notmuch subcommand --uuid=HEX`` is
-equivalent to ``notmuch --uuid=HEX subcommand``.
+command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent
+to ``notmuch --uuid=HEX subcommand``.
COMMANDS
========
The currently available hooks are described below.
- **pre-new**
- This hook is invoked by the **new** command before scanning or
- importing new messages into the database. If this hook exits
- with a non-zero status, notmuch will abort further processing of
- the **new** command.
-
- Typically this hook is used for fetching or delivering new mail
- to be imported into the database.
-
- **post-new**
- This hook is invoked by the **new** command after new messages
- have been imported into the database and initial tags have been
- applied. The hook will not be run if there have been any errors
- during the scan or import.
-
- Typically this hook is used to perform additional query-based
- tagging on the imported messages.
-
- **post-insert**
-
- This hook is invoked by the **insert** command after the
- message has been delivered, added to the database, and initial
- tags have been applied. The hook will not be run if there have
- been any errors during the message delivery; what is regarded
- as successful delivery depends on the ``--keep`` option.
-
- Typically this hook is used to perform additional query-based
- tagging on the delivered messages.
+**pre-new**
+ This hook is invoked by the **new** command before scanning or
+ importing new messages into the database. If this hook exits with
+ a non-zero status, notmuch will abort further processing of the
+ **new** command.
+
+ Typically this hook is used for fetching or delivering new mail to
+ be imported into the database.
+
+**post-new**
+ This hook is invoked by the **new** command after new messages
+ have been imported into the database and initial tags have been
+ applied. The hook will not be run if there have been any errors
+ during the scan or import.
+
+ Typically this hook is used to perform additional query-based
+ tagging on the imported messages.
+
+**post-insert**
+ This hook is invoked by the **insert** command after the message
+ has been delivered, added to the database, and initial tags have
+ been applied. The hook will not be run if there have been any
+ errors during the message delivery; what is regarded as successful
+ delivery depends on the ``--keep`` option.
+
+ Typically this hook is used to perform additional query-based
+ tagging on the delivered messages.
SEE ALSO
========
of its normal activity.
**index.decryption**
-
If a message contains encrypted content, and notmuch tries to
decrypt that content during indexing, it will add the property
``index.decryption=success`` when the cleartext was successfully
results to those whose value matches a regular expression (see
**regex(7)**) delimited with //, for example::
- notmuch search 'from:/bob@.*[.]example[.]com/'
+ notmuch search 'from:"/bob@.*[.]example[.]com/"'
from:<name-or-address> or from:/<regex>/
The **from:** prefix is used to match the name or address of
expression, and supported syntax for <since> and <until> date and
time expressions.
- The time range can also be specified using timestamps with a
- syntax of:
+ The time range can also be specified using timestamps without
+ including the date prefix using a syntax of:
<initial-timestamp>..<final-timestamp>
Each timestamp is a number representing the number of seconds
- since 1970-01-01 00:00:00 UTC.
+ since 1970-01-01 00:00:00 UTC. Specifying a time range this way
+ is considered legacy and predates the date prefix.
lastmod:<initial-revision>..<final-revision>
The **lastmod:** prefix can be used to restrict the result by the
will not.
+Quoting
+-------
+
+Double quotes are also used by the notmuch query parser to protect
+boolean terms or regular expressions containing spaces or other
+special characters, e.g.
+
+::
+
+ tag:"a tag"
+
+::
+
+ folder:"/^.*/(Junk|Spam)$/"
+
+As with phrases, you need to protect the double quotes from the shell
+e.g.
+
+::
+
+ % notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
+
DATE AND TIME SEARCH
====================
could describe (the end of yesterday). Similarly, date:january..february
matches from the beginning of January to the end of February.
+If specifying a time range using timestamps in conjunction with the
+date prefix, each timestamp must be preceded by @ (ASCII hex 40). As
+above, each timestamp is a number representing the number of seconds
+since 1970-01-01 00:00:00 UTC. For example:
+
+ date:@<initial-timestamp>..@<final-timestamp>
+
date:<expr>..! can be used as a shorthand for date:<expr>..<expr>. The
expansion takes place before interpretation, and thus, for example,
date:monday..! matches from the beginning of Monday until the end of
:hide-if-empty - hide if no buttons would be shown
(only makes sense without :show-empty-searches)
:filter - This can be a function that takes the search query as its argument and
- returns a filter to be used in conjuction with the query for that search or nil
+ returns a filter to be used in conjunction with the query for that search or nil
to hide the element. This can also be a string that is used as a combined with
each query using \"and\".
:filter-count - Separate filter to generate the count displayed each search. Accepts
"Function to decide which parts get a header when replying.
This function specifies which parts of a mime message with
-mutiple parts get a header."
+multiple parts get a header."
:type '(radio (const :tag "No part headers"
notmuch-show-reply-insert-header-p-never)
(const :tag "All except multipart/* and hidden parts"
*
* NOTMUCH_STATUS_SUCCESS: excluded was added successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured.
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred.
* Most likely a problem lazily parsing the query string.
*
* NOTMUCH_STATUS_IGNORED: tag is explicitly present in the query, so
*
* NOTMUCH_STATUS_SUCCESS: query completed successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
* value of *count is not defined.
*
* @since libnotmuch 5 (notmuch 0.25)
* NOTMUCH_STATUS_SUCCESS: query completed successfully.
*
- * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occured. The
+ * NOTMUCH_STATUS_XAPIAN_EXCEPTION: a Xapian exception occurred. The
* value of *count is not defined.
*
* @since libnotmuch 5 (notmuch 0.25)
*
* @returns
* - NOTMUCH_STATUS_NULL_POINTER: *value* may not be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * - NOTMUCH_STATUS_SUCCESS: No error occurred.
* @since libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
* @returns
* - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
* - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * - NOTMUCH_STATUS_SUCCESS: No error occurred.
* @since libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
* @returns
* - NOTMUCH_STATUS_ILLEGAL_ARGUMENT: *key* may not contain an '=' character.
* - NOTMUCH_STATUS_NULL_POINTER: Neither *key* nor *value* may be NULL.
- * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * - NOTMUCH_STATUS_SUCCESS: No error occurred.
* @since libnotmuch 4.4 (notmuch 0.23)
*/
notmuch_status_t
* @returns
* - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
* read-only mode so message cannot be modified.
- * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * - NOTMUCH_STATUS_SUCCESS: No error occurred.
*
* @since libnotmuch 4.4 (notmuch 0.23)
*/
* @returns
* - NOTMUCH_STATUS_READ_ONLY_DATABASE: Database was opened in
* read-only mode so message cannot be modified.
- * - NOTMUCH_STATUS_SUCCESS: No error occured.
+ * - NOTMUCH_STATUS_SUCCESS: No error occurred.
*
* @since libnotmuch 5.1 (notmuch 0.26)
*/
* otherwise. Partial results are not cleaned up on errors.
*/
static bool
-maildir_create_folder (const void *ctx, const char *maildir)
+maildir_create_folder (const void *ctx, const char *maildir, bool world_readable)
{
const char *subdirs[] = { "cur", "new", "tmp" };
- const int mode = 0700;
+ const int mode = (world_readable ? 0755 : 0700);
char *subdir;
unsigned int i;
* is not touched).
*/
static int
-maildir_mktemp (const void *ctx, const char *maildir, char **path_out)
+maildir_mktemp (const void *ctx, const char *maildir, bool world_readable, char **path_out)
{
char *filename, *path;
int fd;
+ const int mode = (world_readable ? 0644 : 0600);
do {
filename = tempfilename (ctx);
return -1;
}
- fd = open (path, O_WRONLY | O_CREAT | O_TRUNC | O_EXCL, 0600);
+ fd = open (path, O_WRONLY | O_CREAT | O_TRUNC | O_EXCL, mode);
} while (fd == -1 && errno == EEXIST);
if (fd == -1) {
* the file, or NULL on errors.
*/
static char *
-maildir_write_tmp (const void *ctx, int fdin, const char *maildir)
+maildir_write_tmp (const void *ctx, int fdin, const char *maildir, bool world_readable)
{
char *path;
int fdout;
- fdout = maildir_mktemp (ctx, maildir, &path);
+ fdout = maildir_mktemp (ctx, maildir, world_readable, &path);
if (fdout < 0)
return NULL;
* errors.
*/
static char *
-maildir_write_new (const void *ctx, int fdin, const char *maildir)
+maildir_write_new (const void *ctx, int fdin, const char *maildir, bool world_readable)
{
char *cleanpath, *tmppath, *newpath, *newdir;
- tmppath = maildir_write_tmp (ctx, fdin, maildir);
+ tmppath = maildir_write_tmp (ctx, fdin, maildir, world_readable);
if (! tmppath)
return NULL;
cleanpath = tmppath;
bool create_folder = false;
bool keep = false;
bool hooks = true;
+ bool world_readable = false;
bool synchronize_flags;
char *maildir;
char *newpath;
{ .opt_string = &folder, .name = "folder", .allow_empty = true },
{ .opt_bool = &create_folder, .name = "create-folder" },
{ .opt_bool = &keep, .name = "keep" },
- { .opt_bool = &hooks, .name = "hooks" },
+ { .opt_bool = &hooks, .name = "hooks" },
+ { .opt_bool = &world_readable, .name = "world-readable" },
{ .opt_inherit = notmuch_shared_indexing_options },
{ .opt_inherit = notmuch_shared_options },
{ }
}
strip_trailing (maildir, '/');
- if (create_folder && ! maildir_create_folder (config, maildir))
+ if (create_folder && ! maildir_create_folder (config, maildir, world_readable))
return EXIT_FAILURE;
/* Set up our handler for SIGINT. We do not set SA_RESTART so that copying
sigaction (SIGINT, &action, NULL);
/* Write the message to the Maildir new directory. */
- newpath = maildir_write_new (config, STDIN_FILENO, maildir);
+ newpath = maildir_write_new (config, STDIN_FILENO, maildir, world_readable);
if (! newpath) {
return EXIT_FAILURE;
}
* Notmuch subcommand hook.
*
* The return value will be used as notmuch exit status code,
- * preferrably EXIT_SUCCESS or EXIT_FAILURE.
+ * preferably EXIT_SUCCESS or EXIT_FAILURE.
*/
typedef int (*command_function_t) (notmuch_config_t *config, int argc, char *argv[]);
* seconds. This is useful for callers that require a value for
* inclusive comparison of the result.
*
- * Return 0 (PARSE_TIME_OK) for succesfully parsed date/time, or one
+ * Return 0 (PARSE_TIME_OK) for successfully parsed date/time, or one
* of PARSE_TIME_ERR_* on error. 't' is not modified on error.
*/
int parse_time_string (const char *s, time_t *t, const time_t *ref, int round);
typedef enum {
TAG_PARSE_OUT_OF_MEMORY = -1,
- /* Line parsed successfuly. */
+ /* Line parsed successfully. */
TAG_PARSE_SUCCESS = 0,
/* Line has a syntax error */
test_require_external_prereq gdb
+# subtests about file permissions assume that we're working with umask
+# 022 by default.
+umask 022
+
# Create directories and database before inserting.
mkdir -p "$MAIL_DIR"/{cur,new,tmp}
mkdir -p "$MAIL_DIR"/Drafts/{cur,new,tmp}
cur_msg_filename=$(notmuch search --output=files "subject:insert-subject")
test_expect_equal_file "$cur_msg_filename" "$gen_msg_filename"
+test_begin_subtest "Permissions on inserted message should be 0600"
+test_expect_equal "600" "$(stat -c %a "$cur_msg_filename")"
+
test_begin_subtest "Insert message adds default tags"
output=$(notmuch show --format=json "subject:insert-subject")
expected='[[[{
output=$(notmuch search --output=messages tag:custom)
test_expect_equal "$output" "id:$gen_msg_id"
+test_begin_subtest "Insert tagged world-readable message"
+gen_insert_msg
+notmuch insert --world-readable +world-readable-test < "$gen_msg_filename"
+cur_msg_filename=$(notmuch search --output=files "tag:world-readable-test")
+test_expect_equal_file "$cur_msg_filename" "$gen_msg_filename"
+
+test_begin_subtest "Permissions on inserted world-readable message should be 0644"
+test_expect_equal "644" "$(stat -c %a "$cur_msg_filename")"
+
+test_begin_subtest "Insert tagged world-readable message with group-only umask"
+oldumask=$(umask)
+umask 027
+gen_insert_msg
+notmuch insert --world-readable +world-readable-umask-test < "$gen_msg_filename"
+cur_msg_filename=$(notmuch search --output=files "tag:world-readable-umask-test")
+umask "$oldumask"
+test_expect_equal_file "$cur_msg_filename" "$gen_msg_filename"
+
+test_begin_subtest "Permissions on inserted world-readable message with funny umask should be 0640"
+test_expect_equal "640" "$(stat -c %a "$cur_msg_filename")"
+
test_begin_subtest "Insert message, add/remove tags"
gen_insert_msg
notmuch insert +custom -unread < "$gen_msg_filename"
basename=$(basename "$output")
test_expect_equal_file "$gen_msg_filename" "${MAIL_DIR}/F/G/H/I/J/new/${basename}"
+test_begin_subtest "Created subfolder should have permissions 0700"
+test_expect_equal "700" "$(stat -c %a "${MAIL_DIR}/F/G/H/I/J")"
+test_begin_subtest "Created subfolder new/ should also have permissions 0700"
+test_expect_equal "700" "$(stat -c %a "${MAIL_DIR}/F/G/H/I/J/new")"
+
+test_begin_subtest "Insert message, create world-readable subfolder"
+gen_insert_msg
+notmuch insert --folder=F/G/H/I/J/K --create-folder --world-readable +folder-world-readable < "$gen_msg_filename"
+output=$(notmuch search --output=files path:F/G/H/I/J/K/new tag:folder-world-readable)
+basename=$(basename "$output")
+test_expect_equal_file "$gen_msg_filename" "${MAIL_DIR}/F/G/H/I/J/K/new/${basename}"
+
+test_begin_subtest "Created world-readable subfolder should have permissions 0755"
+test_expect_equal "755" "$(stat -c %a "${MAIL_DIR}/F/G/H/I/J/K")"
+test_begin_subtest "Created world-readable subfolder new/ should also have permissions 0755"
+test_expect_equal "755" "$(stat -c %a "${MAIL_DIR}/F/G/H/I/J/K/new")"
+
test_begin_subtest "Insert message, create existing subfolder"
gen_insert_msg
notmuch insert --folder=F/G/H/I/J --create-folder +folder < "$gen_msg_filename"
output=$(notmuch search 'to:"Search By To Name"' | notmuch_search_sanitize)
test_expect_equal "$output" "thread:XXX 2000-01-01 [1/1] Notmuch Test Suite; search by to (name) (inbox unread)"
-test_begin_subtest "Search by to: (name and adress)"
+test_begin_subtest "Search by to: (name and address)"
output=$(notmuch search 'to:"Search By To Name <test@example.com>"' | notmuch_search_sanitize)
test_expect_equal "$output" "thread:XXX 2000-01-01 [1/1] Notmuch Test Suite; search by to (name) (inbox unread)"
-test_begin_subtest "Search by to: without prefix (name and adress)"
+test_begin_subtest "Search by to: without prefix (name and address)"
output=$(notmuch search '"Search By To Name <test@example.com>"' | notmuch_search_sanitize)
test_expect_equal "$output" "thread:XXX 2000-01-01 [1/1] Notmuch Test Suite; search by to (name) (inbox unread)"
EOF
test_expect_equal_file EXPECTED OUTPUT
-test_begin_subtest "--format=text --part=7, inline attachement"
+test_begin_subtest "--format=text --part=7, inline attachment"
notmuch show --format=text --part=7 'id:87liy5ap00.fsf@yoom.home.cworth.org' >OUTPUT
cat <<EOF >EXPECTED
\fattachment{ ID: 7, Filename: attachment, Content-type: text/plain
EOF
test_expect_equal_file EXPECTED OUTPUT
-test_begin_subtest "test keyword arguments with non-default value separted by a space"
+test_begin_subtest "test keyword arguments with non-default value separated by a space"
$TEST_DIRECTORY/arg-test --boolkeyword false bananas > OUTPUT
cat <<EOF > EXPECTED
boolkeyword 0
notmuch reindex '*'
notmuch dump | grep '^#=' | sort > OUTPUT
test_expect_equal_file prop-dump OUTPUT
-test_done
add_email_corpus lkml
*/
UTIL_EOF,
/**
- * Low level error occured, consult errno.
+ * Low level error occurred, consult errno.
*/
UTIL_ERRNO,
/**
- * Zlib error occured, call gzerror for details.
+ * Zlib error occurred, call gzerror for details.
*/
UTIL_GZERROR
} util_status_t;
== install ==
-Simply run 'make install'. However, check that you have the depencies below.
+Simply run 'make install'. However, check that you have the dependencies below.
=== vim +ruby ===