From: David Bremner Date: Sat, 7 Apr 2018 20:43:01 +0000 (-0300) Subject: Merge branch 'release' X-Git-Tag: 0.27_rc0~47 X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=commitdiff_plain;h=5d510221d17862a252955d98046508bebcd14573;hp=ea690a44d1a5af3da496b0d9482471cbd9623231 Merge branch 'release' --- diff --git a/.travis.yml b/.travis.yml index 802efd98..79802b7b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -10,8 +10,7 @@ addons: - libxapian-dev - libgmime-2.6-dev - libtalloc-dev - - python-sphinx - - gdb + - python3-sphinx - gpgsm script: diff --git a/INSTALL b/INSTALL index 875014f0..69f9df7e 100644 --- a/INSTALL +++ b/INSTALL @@ -84,15 +84,15 @@ Installing Dependencies from Packages ------------------------------------- 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. diff --git a/Makefile.local b/Makefile.local index 1535c2ae..df95f5fc 100644 --- a/Makefile.local +++ b/Makefile.local @@ -176,7 +176,7 @@ verify-newer: 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 diff --git a/NEWS b/NEWS index 39ce7707..fff8a08c 100644 --- a/NEWS +++ b/NEWS @@ -674,7 +674,7 @@ Fixed constant values so they are not all zero anymore 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) =========================== @@ -1454,7 +1454,7 @@ Command-Line Interface 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. @@ -2664,7 +2664,7 @@ Turn "id:MSG-ID" links into buttons associated with notmuch searches 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 @@ -2699,7 +2699,7 @@ mailing list. 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) diff --git a/bindings/python/docs/source/filesystem.rst b/bindings/python/docs/source/filesystem.rst index a23ae41a..558c93de 100644 --- a/bindings/python/docs/source/filesystem.rst +++ b/bindings/python/docs/source/filesystem.rst @@ -14,7 +14,7 @@ Files and directories 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 diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py index a1ae14fc..342d665a 100644 --- a/bindings/python/notmuch/database.py +++ b/bindings/python/notmuch/database.py @@ -566,7 +566,7 @@ class Database(object): :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 @@ -591,7 +591,7 @@ class Database(object): 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" diff --git a/bindings/python/notmuch/filenames.py b/bindings/python/notmuch/filenames.py index 29f4fdf6..3bbc22b9 100644 --- a/bindings/python/notmuch/filenames.py +++ b/bindings/python/notmuch/filenames.py @@ -67,7 +67,7 @@ class Filenames(Python3StringMixIn): 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 diff --git a/bindings/python/notmuch/message.py b/bindings/python/notmuch/message.py index d5b98e4f..1b1f2174 100644 --- a/bindings/python/notmuch/message.py +++ b/bindings/python/notmuch/message.py @@ -223,7 +223,7 @@ class Message(Python3StringMixIn): :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() @@ -295,7 +295,7 @@ class Message(Python3StringMixIn): :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() diff --git a/bindings/python/notmuch/messages.py b/bindings/python/notmuch/messages.py index e17f1507..cae5da50 100644 --- a/bindings/python/notmuch/messages.py +++ b/bindings/python/notmuch/messages.py @@ -100,7 +100,7 @@ class Messages(object): 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 diff --git a/bindings/python/notmuch/tag.py b/bindings/python/notmuch/tag.py index 3b4a56ac..fbb18ce4 100644 --- a/bindings/python/notmuch/tag.py +++ b/bindings/python/notmuch/tag.py @@ -64,7 +64,7 @@ class Tags(Python3StringMixIn): 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 diff --git a/bindings/python/notmuch/thread.py b/bindings/python/notmuch/thread.py index ed961885..9aa0e08c 100644 --- a/bindings/python/notmuch/thread.py +++ b/bindings/python/notmuch/thread.py @@ -71,7 +71,7 @@ class Thread(object): 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* diff --git a/bindings/python/notmuch/threads.py b/bindings/python/notmuch/threads.py index 86f1f2cc..0c382d5b 100644 --- a/bindings/python/notmuch/threads.py +++ b/bindings/python/notmuch/threads.py @@ -85,7 +85,7 @@ class Threads(Python3StringMixIn): 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 diff --git a/contrib/go/src/notmuch/notmuch.go b/contrib/go/src/notmuch/notmuch.go index 89093b2d..5496198a 100644 --- a/contrib/go/src/notmuch/notmuch.go +++ b/contrib/go/src/notmuch/notmuch.go @@ -597,7 +597,7 @@ func (self *Threads) MoveToNext() { * * 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 { @@ -937,7 +937,7 @@ func (self *Message) GetMessageId() string { 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 "" @@ -962,7 +962,7 @@ func (self *Message) GetThreadId() string { 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 { @@ -1019,7 +1019,7 @@ func (self *Message) GetFileName() string { 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 { @@ -1096,7 +1096,7 @@ func (self *Message) GetHeader(header string) string { 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 "" @@ -1335,7 +1335,7 @@ func (self *Tags) Get() string { return "" } s := C.notmuch_tags_get(self.tags) - // we dont own 's' + // we don't own 's' return C.GoString(s) } diff --git a/debian/changelog b/debian/changelog index 0bc2d7bb..4e6cda69 100644 --- a/debian/changelog +++ b/debian/changelog @@ -535,7 +535,7 @@ notmuch (0.18-3) unstable; urgency=medium 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 Thu, 08 May 2014 08:28:33 +0900 @@ -956,7 +956,7 @@ notmuch (0.6.1-1) unstable; urgency=low 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). diff --git a/debian/gbp.conf b/debian/gbp.conf index 6cb451a4..a1c8735d 100644 --- a/debian/gbp.conf +++ b/debian/gbp.conf @@ -7,9 +7,6 @@ upstream-branch = master # 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 diff --git a/devel/release-checks.sh b/devel/release-checks.sh index 5a7578b8..7ba94822 100755 --- a/devel/release-checks.sh +++ b/devel/release-checks.sh @@ -51,7 +51,7 @@ then exit 1 fi else - echo "Reading './version' file failed (suprisingly!)" + echo "Reading './version' file failed (surprisingly!)" exit 1 fi < ./version diff --git a/doc/Makefile.local b/doc/Makefile.local index c6f05ca8..a1739e15 100644 --- a/doc/Makefile.local +++ b/doc/Makefile.local @@ -89,9 +89,9 @@ install-man: 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 diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 68415d13..c00d7d74 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -18,93 +18,89 @@ See **notmuch-search-terms(7)** for details of the supported syntax for 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 =========== diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst index 25692c5b..b05593ec 100644 --- a/doc/man1/notmuch-compact.rst +++ b/doc/man1/notmuch-compact.rst @@ -24,14 +24,14 @@ process (which may be quite long) to protect data integrity. Supported options for **compact** include - ``--backup=``\ - 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=``\ + 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 =========== diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst index 9d6ff107..89909808 100644 --- a/doc/man1/notmuch-config.rst +++ b/doc/man1/notmuch-config.rst @@ -21,203 +21,189 @@ Items marked **[STORED IN DATABASE]** are only in the database. They 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.** - - Compile time feature . Current possibilities include - "compact" (see **notmuch-compact(1)**) - and "field_processor" (see **notmuch-search-terms(7)**). - - **query.** - - **[STORED IN DATABASE]** - Expansion for named query called . 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.** + Compile time feature . Current possibilities include + "compact" (see **notmuch-compact(1)**) and "field_processor" (see + **notmuch-search-terms(7)**). + +**query.** **[STORED IN DATABASE]** + Expansion for named query called . See + **notmuch-search-terms(7)** for more information about named + queries. ENVIRONMENT =========== diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst index 35a2e5e8..9ca20dab 100644 --- a/doc/man1/notmuch-count.rst +++ b/doc/man1/notmuch-count.rst @@ -22,39 +22,38 @@ See **notmuch-search-terms(7)** for details of the supported syntax for 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=``\ - 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=``\ + Read input from given file, instead of from stdin. Implies + ``--batch``. SEE ALSO ======== diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index 7bc57d29..f8ec4868 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -26,86 +26,76 @@ the remaining arguments are search terms. 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=``\ - Write output to given file instead of stdout. +``--output=``\ + Write output to given file instead of stdout. SEE ALSO ======== diff --git a/doc/man1/notmuch-emacs-mua.rst b/doc/man1/notmuch-emacs-mua.rst index 87787e20..a0476136 100644 --- a/doc/man1/notmuch-emacs-mua.rst +++ b/doc/man1/notmuch-emacs-mua.rst @@ -15,49 +15,49 @@ subject, recipients, and message body, or mailto: URL. Supported options for **emacs-mua** include - ``-h, --help`` - Display help. +``-h, --help`` + Display help. - ``-s, --subject=``\ - Specify the subject of the message. +``-s, --subject=``\ + Specify the subject of the message. - ``--to=``\ - Specify a recipient (To). +``--to=``\ + Specify a recipient (To). - ``-c, --cc=``\ - Specify a carbon-copy (Cc) recipient. +``-c, --cc=``\ + Specify a carbon-copy (Cc) recipient. - ``-b, --bcc=``\ - Specify a blind-carbon-copy (Bcc) recipient. +``-b, --bcc=``\ + Specify a blind-carbon-copy (Bcc) recipient. - ``-i, --body=``\ - Specify a file to include into the body of the message. +``-i, --body=``\ + 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 diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index 1a3dfe98..86e2f567 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -31,48 +31,52 @@ more details on hooks. 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 =========== diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst index 3ddd4621..16af5492 100644 --- a/doc/man1/notmuch-new.rst +++ b/doc/man1/notmuch-new.rst @@ -37,29 +37,27 @@ details on hooks. 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 =========== diff --git a/doc/man1/notmuch-reindex.rst b/doc/man1/notmuch-reindex.rst index 8b3083cf..cd7c91a0 100644 --- a/doc/man1/notmuch-reindex.rst +++ b/doc/man1/notmuch-reindex.rst @@ -21,34 +21,71 @@ messages using the supplied options. 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)**, diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst index 1b62e075..c893ba04 100644 --- a/doc/man1/notmuch-reply.rst +++ b/doc/man1/notmuch-reply.rst @@ -34,64 +34,62 @@ The resulting message template is output to stdout. 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 . diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst index b578af1f..c0f47f26 100644 --- a/doc/man1/notmuch-restore.rst +++ b/doc/man1/notmuch-restore.rst @@ -16,68 +16,62 @@ The input is read from the given filename, if any, or from stdin. 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=``\ - 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=``\ + Read input from given file instead of stdin. GZIPPED INPUT ============= diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index 67c1ce90..181058c6 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -24,118 +24,118 @@ See **notmuch-search-terms(7)** for details of the supported syntax for 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 ======= diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index 7d2b38cb..2b825ccc 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -23,149 +23,143 @@ post-processor (such as the emacs interface to notmuch). 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:" as can be diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst index 88e454ba..c2324f5a 100644 --- a/doc/man1/notmuch-tag.rst +++ b/doc/man1/notmuch-tag.rst @@ -32,23 +32,22 @@ the **maildir.synchronize\_flags** configuration option is enabled. See 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=``\ - 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=``\ + Read input from given file, instead of from stdin. Implies + ``--batch``. TAG FILE FORMAT =============== diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst index 358f42e8..d2cd8da5 100644 --- a/doc/man1/notmuch.rst +++ b/doc/man1/notmuch.rst @@ -39,28 +39,27 @@ OPTIONS 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 ======== diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst index f07e4dab..de2ed0c2 100644 --- a/doc/man5/notmuch-hooks.rst +++ b/doc/man5/notmuch-hooks.rst @@ -17,34 +17,33 @@ have executable permissions. 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 ======== diff --git a/doc/man7/notmuch-properties.rst b/doc/man7/notmuch-properties.rst index 07d36a1a..802e6763 100644 --- a/doc/man7/notmuch-properties.rst +++ b/doc/man7/notmuch-properties.rst @@ -54,7 +54,6 @@ The following properties are set by notmuch internally in the course 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 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index 6d2bf62a..b4d784a3 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -121,13 +121,14 @@ date:.. or date: expression, and supported syntax for and 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: .. 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:.. The **lastmod:** prefix can be used to restrict the result by the @@ -296,6 +297,13 @@ In this case, is taken as the earliest time it could describe 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:@..@ + date:..! can be used as a shorthand for date:... The expansion takes place before interpretation, and thus, for example, date:monday..! matches from the beginning of Monday until the end of diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el index c858a20b..aff8beb5 100644 --- a/emacs/notmuch-hello.el +++ b/emacs/notmuch-hello.el @@ -864,7 +864,7 @@ Supports the following entries in OPTIONS as a plist: :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 diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el index 59b546a6..fc8ac687 100644 --- a/emacs/notmuch-mua.el +++ b/emacs/notmuch-mua.el @@ -103,7 +103,7 @@ Note that these functions use `mail-citation-hook' if that is non-nil." "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" diff --git a/lib/notmuch.h b/lib/notmuch.h index ab5854d7..4db28a05 100644 --- a/lib/notmuch.h +++ b/lib/notmuch.h @@ -869,7 +869,7 @@ notmuch_query_get_sort (const notmuch_query_t *query); * * 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 @@ -1065,7 +1065,7 @@ notmuch_threads_destroy (notmuch_threads_t *threads); * * 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) @@ -1101,7 +1101,7 @@ notmuch_query_count_messages_st (notmuch_query_t *query, unsigned int *count); * 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) @@ -1778,7 +1778,7 @@ notmuch_message_destroy (notmuch_message_t *message); * * @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 @@ -1790,7 +1790,7 @@ notmuch_message_get_property (notmuch_message_t *message, const char *key, const * @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 @@ -1804,7 +1804,7 @@ notmuch_message_add_property (notmuch_message_t *message, const char *key, const * @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 @@ -1819,7 +1819,7 @@ notmuch_message_remove_property (notmuch_message_t *message, const char *key, co * @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) */ @@ -1835,7 +1835,7 @@ notmuch_message_remove_all_properties (notmuch_message_t *message, const char *k * @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) */ diff --git a/notmuch-insert.c b/notmuch-insert.c index 48490b51..d229c9dc 100644 --- a/notmuch-insert.c +++ b/notmuch-insert.c @@ -159,10 +159,10 @@ mkdir_recursive (const void *ctx, const char *path, int mode) * 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; @@ -211,10 +211,11 @@ tempfilename (const void *ctx) * 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); @@ -227,7 +228,7 @@ maildir_mktemp (const void *ctx, const char *maildir, char **path_out) 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) { @@ -289,12 +290,12 @@ copy_fd (int fdout, int fdin) * 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; @@ -323,11 +324,11 @@ FAIL: * 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; @@ -457,6 +458,7 @@ notmuch_insert_command (notmuch_config_t *config, int argc, char *argv[]) bool create_folder = false; bool keep = false; bool hooks = true; + bool world_readable = false; bool synchronize_flags; char *maildir; char *newpath; @@ -467,7 +469,8 @@ notmuch_insert_command (notmuch_config_t *config, int argc, char *argv[]) { .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 }, { } @@ -523,7 +526,7 @@ notmuch_insert_command (notmuch_config_t *config, int argc, char *argv[]) } 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 @@ -535,7 +538,7 @@ notmuch_insert_command (notmuch_config_t *config, int argc, char *argv[]) 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; } diff --git a/notmuch.c b/notmuch.c index 2d193aa8..7810b685 100644 --- a/notmuch.c +++ b/notmuch.c @@ -26,7 +26,7 @@ * 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[]); diff --git a/parse-time-string/parse-time-string.h b/parse-time-string/parse-time-string.h index 2063bcad..c394ecde 100644 --- a/parse-time-string/parse-time-string.h +++ b/parse-time-string/parse-time-string.h @@ -90,7 +90,7 @@ enum { * 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); diff --git a/tag-util.h b/tag-util.h index a2f0ddfa..ba0d98c8 100644 --- a/tag-util.h +++ b/tag-util.h @@ -36,7 +36,7 @@ typedef enum { typedef enum { TAG_PARSE_OUT_OF_MEMORY = -1, - /* Line parsed successfuly. */ + /* Line parsed successfully. */ TAG_PARSE_SUCCESS = 0, /* Line has a syntax error */ diff --git a/test/T070-insert.sh b/test/T070-insert.sh index 40519bb2..05be473a 100755 --- a/test/T070-insert.sh +++ b/test/T070-insert.sh @@ -4,6 +4,10 @@ test_description='"notmuch insert"' 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} @@ -37,6 +41,9 @@ notmuch insert < "$gen_msg_filename" 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='[[[{ @@ -73,6 +80,27 @@ notmuch insert +custom < "$gen_msg_filename" 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" @@ -170,6 +198,23 @@ output=$(notmuch search --output=files path:F/G/H/I/J/new tag:folder) 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" diff --git a/test/T080-search.sh b/test/T080-search.sh index 70f28549..a3f0dead 100755 --- a/test/T080-search.sh +++ b/test/T080-search.sh @@ -85,11 +85,11 @@ add_message '[subject]="search by to (name)"' '[date]="Sat, 01 Jan 2000 12:00:00 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 "' | 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 "' | notmuch_search_sanitize) test_expect_equal "$output" "thread:XXX 2000-01-01 [1/1] Notmuch Test Suite; search by to (name) (inbox unread)" diff --git a/test/T190-multipart.sh b/test/T190-multipart.sh index f73535b7..3eeac1db 100755 --- a/test/T190-multipart.sh +++ b/test/T190-multipart.sh @@ -319,7 +319,7 @@ This is an embedded message, with a multipart/alternative part. 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 <EXPECTED attachment{ ID: 7, Filename: attachment, Content-type: text/plain diff --git a/test/T410-argument-parsing.sh b/test/T410-argument-parsing.sh index a384ce86..b31d239a 100755 --- a/test/T410-argument-parsing.sh +++ b/test/T410-argument-parsing.sh @@ -73,7 +73,7 @@ positional arg 1 bananas 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 < EXPECTED boolkeyword 0 diff --git a/util/util.h b/util/util.h index d12fadb4..b24860af 100644 --- a/util/util.h +++ b/util/util.h @@ -15,11 +15,11 @@ typedef enum util_status { */ 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; diff --git a/vim/README b/vim/README index d6f23350..c137bacd 100644 --- a/vim/README +++ b/vim/README @@ -5,7 +5,7 @@ utilizing the notmuch framework, through it's ruby bindings. == 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 ===