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

106 lines
3.2 KiB
ReStructuredText
Raw Permalink Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-reindex(1):
add "notmuch reindex" subcommand This new subcommand takes a set of search terms, and re-indexes the list of matching messages.
2017-06-04 14:32:35 +02:00
===============
notmuch-reindex
===============
SYNOPSIS
========
**notmuch** **reindex** [*option* ...] <*search-term*> ...
DESCRIPTION
===========
Re-index all messages matching the search terms.
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
See :any:`notmuch-search-terms(7)` for details of the supported syntax for
add "notmuch reindex" subcommand This new subcommand takes a set of search terms, and re-indexes the list of matching messages.
2017-06-04 14:32:35 +02:00
<*search-term*\ >.
The **reindex** command searches for all messages matching the
supplied search terms, and re-creates the full-text index on these
messages using the supplied options.
cli/reindex: add --try-decrypt=(true|false) Enable override of the index.try_decrypt setting on a per-run basis when invoking "notmuch reindex". This allows the possibility of (for example) an emacs keybinding that adds the cleartext of the currently shown decrypted message to the index, making it searchable in the future. It also enables one-time indexing of all messages matching some query, like so: notmuch reindex tag:encrypted and\ not property:index.decryption=success and\ from:alice@example.org We also update the documentation and tab completion, and add a few more tests.
2017-10-21 04:25:48 +02:00
Supported options for **reindex** include
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. program:: reindex
.. option:: --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.
``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.
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 :any:`notmuch-config(1)`.
cli/reindex: add --try-decrypt=(true|false) Enable override of the index.try_decrypt setting on a per-run basis when invoking "notmuch reindex". This allows the possibility of (for example) an emacs keybinding that adds the cleartext of the currently shown decrypted message to the index, making it searchable in the future. It also enables one-time indexing of all messages matching some query, like so: notmuch reindex tag:encrypted and\ not property:index.decryption=success and\ from:alice@example.org We also update the documentation and tab completion, and add a few more tests.
2017-10-21 04:25:48 +02:00
doc: Examples of notmuch-reindex use and crypto policy Currently, notmuch has the levers needed to set coherent crypto policy around how cleartext is indexed, which also has an impact on how messages are rendered. But we don't have a lot of documentation about how to do sensible things. This is an initial attempt to address that. The first example shows a way to selectively index specific messages. The next two examples are about aligning the existing database with crypto indexing policy The default crypto policy is to not index cleartext, and to only decrypt messages on display when explicitly requested. The other sensible crypto policy is to index cleartext while stashing session keys. messages indexed in this way will be searchable, and will be decrypted on display automatically unless the user explicitly asks for it to *not* be decrypted. The policy for indexing *new* messages is stored in the database as the config variable index.decrypt. But setting policy for new messages doesn't retroactively affect already indexed messages. This patch attempts to document ways that someone can efficiently align their pre-existing database with their new policy. I'm not sure this is the right place to document these examples, but i do want them to be user-facing and relatively easy to find. I'm happy to entertain suggestions for where else we should put them.
2018-02-21 18:50:27 +01:00
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
add "notmuch reindex" subcommand This new subcommand takes a set of search terms, and re-indexes the list of matching messages.
2017-06-04 14:32:35 +02:00
SEE ALSO
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch(1)`,
:any:`notmuch-compact(1)`,
:any:`notmuch-config(1)`,
:any:`notmuch-count(1)`,
:any:`notmuch-dump(1)`,
:any:`notmuch-hooks(5)`,
:any:`notmuch-insert(1)`,
:any:`notmuch-new(1)`,
:any:`notmuch-reply(1)`,
:any:`notmuch-restore(1)`,
:any:`notmuch-search(1)`,
:any:`notmuch-search-terms(7)`,
:any:`notmuch-show(1)`,
:any:`notmuch-tag(1)`
Reference in a new issue Copy permalink