NOTMUCH-CONFIG(1)

NAME

       notmuch-config - access notmuch configuration file

SYNOPSIS

       notmuch config get <section>.<item>

       notmuch config set [--database] <section>.<item> [value ...]

       notmuch config list

DESCRIPTION

       The  config  command  can be used to get or set settings in the notmuch
       configuration file and corresponding database.

       get    The value of the specified configuration item is printed to std‐
              out.  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.

              If no values are provided, the specified configuration item will
              be removed from the configuration file.

              With  the  --database  option,  updates  configuration  metadata
              stored in the database, rather than the default (text)  configu‐
              ration file.

       list   Every  configuration  item is printed to stdout, each on a sepa‐
              rate line of the form:

                 section.item=value

              No additional whitespace surrounds the dot or equals sign  char‐
              acters.  In a multiple-value item (a list), the values are sepa‐
              rated by semicolon characters.

       The available configuration items  are  described  below.  Non-absolute
       paths are presumed relative to $HOME for items in section database.

       database.path
              Notmuch  will  store  its database here, (in sub-directory named
              .notmuch if database.mail_root is unset).

              Default: see DATABASE LOCATION

       database.mail_root
              The top-level directory where your mail currently exists and  to
              where  mail will be delivered in the future. Files should be in‐
              dividual email messages.

              History: this configuration  value  was  introduced  in  notmuch
              0.32.

              Default:  For compatibility with older configurations, the value
              of database.path is used if database.mail_root is unset.

       database.backup_dir
              Directory to store tag dumps when upgrading database.

              History: this configuration  value  was  introduced  in  notmuch
              0.32.

              Default: A sibling directory of the Xapian database called back‐
              ups.

       database.hook_dir
              Directory containing hooks run by  notmuch  commands.  See  not‐
              much-hooks(5).

              History:  this  configuration  value  was  introduced in notmuch
              0.32.

              Default: See HOOKS, below.

       database.autocommit
          How often to commit transactions to disk. 0 means wait until command
          completes,  otherwise an integer n specifies to commit to disk after
          every n completed transactions.

          History: this configuration value was introduced in notmuch 0.33.

       user.name
              Your full name.

              Default: $NAME variable if set, otherwise read from /etc/passwd.

       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(1). 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 hierar‐
              chy.

              Or:

              A regular expression delimited with  //  that  will  be  matched
              against  the path of the file or directory relative to the data‐
              base path. Matching files and directories will be  ignored.  The
              beginning and end of string must be explicitly anchored. For ex‐
              ample, /.*/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 de‐
              fault. Using an excluded tag in a query will override  that  ex‐
              clusion.

              Default:   empty   list.   Note   that   notmuch-setup(1)   puts
              deleted;spam here when creating new configuration file.

       show.extra_headers
          By default notmuch-show(1) includes the following headers in  struc‐
          tured  output if they are present in the message: Subject, From, To,
          Cc, Bcc, Reply-To, Date. This option allows the specification  of  a
          list of further headers to output.

          History: This configuration value was introduced in notmuch 0.35.

          Default: empty list.

       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(1) command will notice flag changes in filenames
              and update tags, while the notmuch-tag(1) and notmuch-restore(1)
              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(1)  before  not‐
              much-tag(1) or notmuch-restore(1) 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.

       index.decrypt
              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-in‐
              sert(1), or notmuch-reindex(1)), the user can override the data‐
              base'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 cleart‐ │       │ X    │ X       │ X    │
                      │ext     using │       │      │         │      │
                      │stashed  ses‐ │       │      │         │      │
                      │sion keys     │       │      │         │      │
                      ├──────────────┼───────┼──────┼─────────┼──────┤
                      │Index cleart‐ │       │      │ X       │ X    │
                      │ext using se‐ │       │      │         │      │
                      │cret keys     │       │      │         │      │
                      ├──────────────┼───────┼──────┼─────────┼──────┤
                      │Stash session │       │      │         │ X    │
                      │keys
                      ├──────────────┼───────┼──────┼─────────┼──────┤
                      │Delete
                      │stashed  ses‐ │       │      │         │      │
                      │sion keys  on │       │      │         │      │
                      │reindex       │       │      │         │      │
                      └──────────────┴───────┴──────┴─────────┴──────┘

              Stashed  session keys are kept in the database as properties as‐
              sociated with the message.  See session-key  in  notmuch-proper‐
              ties(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 not‐
              much message index is adequately  protected.   DO  NOT  USE  in-
              dex.decrypt=true  or  index.decrypt=nostash  without considering
              the security of your index.

              Default: auto.

       index.header.<prefix>
              Define the query prefix <prefix>, based on a  mail  header.  For
              example  index.header.List=List-Id will add a probabilistic pre‐
              fix List: that searches the List-Id field.   User  defined  pre‐
              fixes must not start with 'a'...'z'; in particular adding a pre‐
              fix with same name as a predefined prefix is not supported.  See
              notmuch-search-terms(7)  for a list of existing prefixes, and an
              explanation of probabilistic prefixes.

       built_with.<name>
              Compile  time  feature  <name>.  Current  possibilities  include
              "retry_lock"  (configure  option,  included by default).  (since
              notmuch 0.30, "compact" and  "field_processor"  are  always  in‐
              cluded.)

       query.<name>
              Expansion    for   named   query   called   <name>.   See   not‐
              much-search-terms(7) for more information about named queries.

       squery.<name>
              Expansion for named query called <name>, using s-expression syn‐
              tax.  See  notmuch-sexp-queries(7)  for  more  information about
              s-expression queries.

FILES

  CONFIGURATION

       Notmuch configuration file search order:

       1. File specified by notmuch --config global option; see notmuch(1).

       2. File specified by NOTMUCH_CONFIG environment variable.

       3. $XDG_CONFIG_HOME/notmuch/<profile>/config where <profile> is defined
          by   NOTMUCH_PROFILE   environment   variable   if   set,  $XDG_CON-
          FIG_HOME/notmuch/default/config otherwise.

       4. $HOME/.notmuch-config.<profile> where <profile> is defined  by  NOT-
          MUCH_PROFILE environment variable if set, $HOME/.notmuch-config oth‐
          erwise.

  DATABASE LOCATION

       Notmuch database search order:

       1. Directory specified by NOTMUCH_DATABASE environment variable.

       2. Directory specified by config key database.path.

       3. $XDG_DATA_HOME/notmuch/<profile> where <profile> is defined by  NOT-
          MUCH_PROFILE environment variable if set, $XDG_DATA_HOME/notmuch/de-
          fault otherwise.

       4. Directory specified by MAILDIR environment variable.

       5. $HOME/mail

  HOOKS

       Notmuch hook directory search order:

       1. Directory specified by database.hook_dir configuration option.

       2. $XDG_CONFIG_HOME/notmuch/<profile>/hooks where <profile> is  defined
          by   NOTMUCH_PROFILE   environment   variable   if   set,  $XDG_CON-
          FIG_HOME/notmuch/default/hooks otherwise.

       3. <database.path>/.notmuch/hooks

SEE ALSO

       notmuch(1), notmuch-count(1), notmuch-dump(1),  notmuch-hooks(5),  not‐
       much-insert(1),   notmuch-new(1),   notmuch-properties(7),  notmuch-re‐
       ply(1), notmuch-restore(1), notmuch-search(1), notmuch-search-terms(7),
       notmuch-show(1), notmuch-tag(1)

AUTHOR

       Carl Worth and many others

COPYRIGHT

       2009-2022, Carl Worth and many others

0.35