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

238 lines
7.7 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(1):
.. _notmuch-setup(1):
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
=======
notmuch
=======
SYNOPSIS
========
**notmuch** [option ...] **command** [arg ...]
DESCRIPTION
===========
Notmuch is a command-line based program for indexing, searching,
reading, and tagging large collections of email messages.
This page describes how to get started using notmuch from the command
line, and gives a brief overview of the commands available. For more
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
information on e.g. **notmuch show** consult the
:any:`notmuch-show(1)` man page, also accessible via **notmuch help
show**
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
The quickest way to get started with Notmuch is to simply invoke the
``notmuch`` command with no arguments, which will interactively guide
you through the process of indexing your mail.
NOTE
====
While the command-line program ``notmuch`` provides powerful
functionality, it does not provide the most convenient interface for
that functionality. More sophisticated interfaces are expected to be
built on top of either the command-line interface, or more likely, on
Use https instead of http where possible Many of the external links found in the notmuch source can be resolved using https instead of http. This changeset addresses as many as i could find, without touching the e-mail corpus or expected outputs found in tests.
2016-06-02 18:26:14 +02:00
top of the notmuch library interface. See https://notmuchmail.org for
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
more about alternate interfaces to notmuch. The emacs-based interface to
notmuch (available under **emacs/** in the Notmuch source distribution)
is probably the most widely used at this time.
OPTIONS
=======
Supported global options for ``notmuch`` 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:: notmuch
.. option:: --help [command-name]
Print a synopsis of available commands and exit. With an optional
command name, show the man page for that subcommand.
.. option:: --version
Print the installed version of notmuch, and exit.
.. option:: --config=FILE
Specify the configuration file to use. This overrides any
configuration file specified by :envvar:`NOTMUCH_CONFIG`. The empty
string is a permitted and sometimes useful value of *FILE*, which
tells ``notmuch`` to use only configuration metadata from the database.
.. option:: --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``
cli: add global option "--uuid" The function notmuch_exit_if_unmatched_db_uuid is split from notmuch_process_shared_options because it needs an open notmuch database. There are two exceptional cases in uuid handling. 1) notmuch config and notmuch setup don't currently open the database, so it doesn't make sense to check the UUID. 2) notmuch compact opens the database inside the library, so we either need to open the database just to check uuid, or change the API.
2015-04-06 00:39:55 +02:00
doc: add minimal note about shared options. The example is a bit silly, but notmuch subcommand --help is actually not equivalent to "notmuch --help subcommand".
2015-06-04 07:32:42 +02:00
All global options except ``--config`` can also be specified after the
doc: unify definition list usage across man pages Make all parameter descriptions etc. use reStructuredText definition lists with uniform style and indentation. Remove redundant indentation from around the lists. Remove blank lines between term lines and definition blocks. Use four spaces for indentation. This is almost completely whitespace and paragraph reflow changes.
2017-12-30 18:16:11 +01:00
command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent
to ``notmuch --uuid=HEX subcommand``.
doc: add minimal note about shared options. The example is a bit silly, but notmuch subcommand --help is actually not equivalent to "notmuch --help subcommand".
2015-06-04 07:32:42 +02:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
COMMANDS
========
SETUP
-----
The **notmuch setup** command is used to configure Notmuch for first
use, (or to reconfigure it later).
The setup command will prompt for your full name, your primary email
address, any alternate email addresses you use, and the directory
containing your email archives. Your answers will be written to a
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
configuration file in :envvar:`NOTMUCH_CONFIG` (if set) or
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
${HOME}/.notmuch-config . This configuration file will be created with
descriptive comments, making it easy to edit by hand later to change the
configuration. Or you can run **notmuch setup** again to change the
configuration.
The mail directory you specify can contain any number of sub-directories
and should primarily contain only files with individual email messages
(eg. maildir or mh archives are perfect). If there are other, non-email
files (such as indexes maintained by other email programs) then notmuch
will do its best to detect those and ignore them.
Mail storage that uses mbox format, (where one mbox file contains many
messages), will not work with notmuch. If that's how your mail is
currently stored, it is recommended you first convert it to maildir
doc: use manpage role references to external man pages Using manpage role references generates helpful links in html documentation, while retaining the same boldface style in the man pages. The external man page site is configurable. The Debian manpage site seems like a good fit for Notmuch.
2021-05-21 22:44:09 +02:00
format with a utility such as :manpage:`mb2md(1)` before running
**notmuch setup**.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Invoking ``notmuch`` with no command argument will run **setup** if the
setup command has not previously been completed.
OTHER COMMANDS
--------------
Several of the notmuch commands accept search terms with a common
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
syntax. See :any:`notmuch-search-terms(7)` for more details on the
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
supported syntax.
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
The :any:`notmuch-search(1)`, :any:`notmuch-show(1)`,
:any:`notmuch-address(1)` and :any:`notmuch-count(1)` commands are
used to query the email database.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: 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
The :any:`notmuch-reply(1)` command is useful for preparing a template
for an email reply.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: 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
The :any:`notmuch-tag(1)` command is the only command available for
manipulating database contents.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: 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
The :any:`notmuch-dump(1)` and :any:`notmuch-restore(1)` commands can
be used to create a textual dump of email tags for backup purposes,
and to restore from that dump.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: 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
The :any:`notmuch-config(1)` command can be used to get or set
settings in the notmuch configuration file.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc/notmuch: merge two sections on external commands. When adding the description of the propagation of NOTMUCH_CONFIG, I missed that there was already a section on external commands, with a different title.
2022-07-31 01:45:49 +02:00
EXTERNAL COMMANDS
-----------------
man: document external subcommand handling in notmuch(1) The documentation for this was overlooked when adding the subcommand handling. This seems like the proper place for it.
2017-03-06 20:26:59 +01:00
If the given command is not known to notmuch, notmuch tries to execute
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
the external **notmuch-<subcommand>** in :envvar:`PATH` instead. This
allows users to have their own notmuch related tools to be run via the
man: document external subcommand handling in notmuch(1) The documentation for this was overlooked when adding the subcommand handling. This seems like the proper place for it.
2017-03-06 20:26:59 +01:00
notmuch command. By design, this does not allow notmuch's own commands
doc/notmuch: merge two sections on external commands. When adding the description of the propagation of NOTMUCH_CONFIG, I missed that there was already a section on external commands, with a different title.
2022-07-31 01:45:49 +02:00
to be overridden using external commands. The environment variable
:envvar:`NOTMUCH_CONFIG` will be set according to :option:`--config`,
if the latter is present.
man: document external subcommand handling in notmuch(1) The documentation for this was overlooked when adding the subcommand handling. This seems like the proper place for it.
2017-03-06 20:26:59 +01:00
cli: add space separator for keyword, string, and int arguments Defer the complication of optional boolean arguments for later (never?).
2017-07-01 17:18:45 +02:00
OPTION SYNTAX
-------------
All options accepting an argument can be used with '=' or ':' as a
notmuch(1): clarify documentation about --option/value separators id:CA+Tk8fzRiqxWpd=r8=DRvEewNZXUZgD7MKyRLB1A=R-LxxGEZw@mail.gmail.com started a thread of discussion that showed that the cli's current idiosyncrasies around dealing with boolean options were not understandable. This attempts to improve the documentation at least (actual changes to the API might be better, but have not reached consensus). Note that no one in the discussion thread identified any other (non-boolean) command-line options that cannot use space as a separator. If such an option is identified (or introduced in the future), it should be added explicitly to this part of the manual. Signed-off-by: Daniel Kahn Gillmor <dkg@fifthhorseman.net>
2020-05-07 21:26:45 +02:00
separator. Except for boolean options (which would be ambiguous), a
space can also be used as a separator. The following are all
equivalent:
cli: add space separator for keyword, string, and int arguments Defer the complication of optional boolean arguments for later (never?).
2017-07-01 17:18:45 +02:00
::
notmuch --config=alt-config config get user.name
notmuch --config:alt-config config get user.name
notmuch --config alt-config config get user.name
doc: add some documentation about duplicate files. This is mainly motivated by the new emacs-UI features to select duplicates, but hopefully it will help demystify things for users of the CLI as well.
2022-07-31 01:45:51 +02:00
.. _duplicate-files:
DUPLICATE MESSAGE FILES
=======================
Notmuch considers the :mailheader:`Message-ID` to be the primary
identifier of message. Per :rfc:`5322` the :mailheader:`Message-ID` is
supposed to be globally unique, but this fails in two distinct
ways. When you receive copies of a message via a mechanism like
:mailheader:`Cc` or via a mailing list, the copies are typically
interchangeable. In the case of some broken mail sending software, the
same :mailheader:`Message-ID` is used for completely unrelated
messages. The options :option:`search --duplicate` and :option:`show
--duplicate` options provide the user with control over which message
file is displayed. Front ends will need to provide their own
interface, see e.g. the Emacs front-end :any:`emacs-show-duplicates`.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
ENVIRONMENT
===========
The following environment variables can be used to control the behavior
of notmuch.
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
.. envvar:: NOTMUCH_CONFIG
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
Specifies the location of the notmuch configuration file. See
:any:`notmuch-config(1)` for details.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
doc: document database search algorithm. Essentially a translation of the function _choose_database_path for human consumption. As a bonus, document environment variable NOTMUCH_DATABASE
2021-08-04 12:42:36 +02:00
.. envvar:: NOTMUCH_DATABASE
Specifies the location of the notmuch database. See
:any:`notmuch-config(1)` for details.
doc: use envvar directive and role for environment variables Make man1/notmuch.rst the single point of truth for describing notmuch environment variables. Use the envvar directive for that, and reference them with the envvar role. Drive-by cleanup configuration file and hook directory search order documentation.
2021-05-21 22:44:11 +02:00
.. envvar:: NOTMUCH_PROFILE
Selects among notmuch configurations. See :any:`notmuch-config(1)`
for details.
.. envvar:: NOTMUCH_TALLOC_REPORT
Location to write a talloc memory usage report. See
**talloc\_enable\_leak\_report\_full** in :manpage:`talloc(3)` for more
information.
.. envvar:: NOTMUCH_DEBUG_QUERY
If set to a non-empty value, the notmuch library will print (to
stderr) Xapian queries it constructs.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
SEE ALSO
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
:any:`notmuch-address(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-properties(7)`,
:any:`notmuch-reindex(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)`
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Use https instead of http where possible Many of the external links found in the notmuch source can be resolved using https instead of http. This changeset addresses as many as i could find, without touching the e-mail corpus or expected outputs found in tests.
2016-06-02 18:26:14 +02:00
The notmuch website: **https://notmuchmail.org**
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
CONTACT
=======
Feel free to send questions, comments, or kudos to the notmuch mailing
list <notmuch@notmuchmail.org> . Subscription is not required before
posting, but is available from the notmuchmail.org website.
Real-time interaction with the Notmuch community is available via IRC
replace references to freenode with references to libera I left the reference to freenode in the test suite data, since it is historical.
2021-07-06 22:19:03 +02:00
(server: irc.libera.chat, channel: #notmuch).
Reference in a new issue Copy permalink