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.
-
-``--version``
- Print the installed version of notmuch, and exit.
-
-``--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.
-
-``--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``
+.. 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``
All global options except ``--config`` can also be specified after the
command. For example, ``notmuch subcommand --uuid=HEX`` is equivalent
The :any:`notmuch-config(1)` command can be used to get or set
settings in the notmuch configuration file.
-CUSTOM COMMANDS
----------------
+EXTERNAL COMMANDS
+-----------------
If the given command is not known to notmuch, notmuch tries to execute
the external **notmuch-<subcommand>** in :envvar:`PATH` instead. This
allows users to have their own notmuch related tools to be run via the
notmuch command. By design, this does not allow notmuch's own commands
-to be overridden using external commands.
+to be overridden using external commands. The environment variable
+:envvar:`NOTMUCH_CONFIG` will be set according to :option:`--config`,
+if the latter is present.
OPTION SYNTAX
-------------
notmuch --config:alt-config config get user.name
notmuch --config alt-config config get user.name
+.. _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`.
+
ENVIRONMENT
===========
Specifies the location of the notmuch configuration file. See
:any:`notmuch-config(1)` for details.
+.. envvar:: NOTMUCH_DATABASE
+
+ Specifies the location of the notmuch database. See
+ :any:`notmuch-config(1)` for details.
+
.. envvar:: NOTMUCH_PROFILE
Selects among notmuch configurations. See :any:`notmuch-config(1)`
posting, but is available from the notmuchmail.org website.
Real-time interaction with the Notmuch community is available via IRC
-(server: irc.freenode.net, channel: #notmuch).
+(server: irc.libera.chat, channel: #notmuch).