man: document the notmuch configuration settings in notmuch-config(1)
[notmuch] / man / man1 / notmuch-config.1
index cb3234ff7ff18fcd165be826c06a1d013092f495..0260eb7952b5f6817b515c60b3a959739975788b 100644 (file)
@@ -1,6 +1,6 @@
 .TH NOTMUCH-CONFIG 1 2011-12-04 "Notmuch 0.10.2"
 .SH NAME
-notmuch-config \- Output a single part of a multipart MIME message.
+notmuch-config \- Access notmuch configuration file.
 .SH SYNOPSIS
 
 .B notmuch config get
@@ -16,34 +16,125 @@ The
 command can be used to get or set settings in the notmuch
 configuration file.
 
-.SS GET
-
+.RS 4
+.TP 4
+.B get
 The value of the specified configuration item is printed to stdout. If
-the item has multiple values, each value is separated by a newline
-character.
+the item has multiple values (it is a list), each value is separated
+by a newline character.
+.RE
 
-Available configuration items include at least
+.RS 4
+.TP 4
+.B 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.
 
-       database.path
+If no values are provided, the specified configuration item will be
+removed from the configuration file.
+.RE
 
-       user.name
+The available configuration items are described below.
 
-       user.primary_email
+.RS 4
+.TP 4
+.B 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
+.BR ".notmuch".
+.RE
 
-       user.other_email
+.RS 4
+.TP 4
+.B user.name
+Your full name.
+.RE
 
-       new.tags
+.RS 4
+.TP 4
+.B user.primary_email
+Your primary email address.
+.RE
 
-.SS SET
+.RS 4
+.TP 4
+.B user.other_email
+A list of other email addresses at which you receive email.
+.RE
 
-The specified configuration item is set to the given value.  To
-specify a multiple-value item, provide each value as a separate
-command-line argument.
+.RS 4
+.TP 4
+.B new.tags
+A list of tags that will be added to all messages incorporated by
+.BR "notmuch new".
+.RE
 
-If no values are provided, the specified configuration item will be
-removed from the configuration file.
+.RS 4
+.TP 4
+.B new.ignore
+A list of file and directory names, without path, that will not be
+searched for messages by
+.BR "notmuch new".
+All the files and directories matching any of the names specified here
+will be ignored, regardless of the location in the mail store
+directory hierarchy.
 .RE
 
+.RS 4
+.TP 4
+.B search.exclude
+A list of tags that will be excluded from search results by
+default. Using an excluded tag in a query will override that
+exclusion.
+.RE
+
+.RS 4
+.TP 4
+.B 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
+.B notmuch new
+command will notice flag changes in filenames and update tags, while
+the
+.B notmuch tag
+and
+.B 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
+.B notmuch new
+before
+.B notmuch tag
+or
+.B 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.
+.RE
+
+.RE
+.SH ENVIRONMENT
+The following environment variables can be used to control the
+behavior of notmuch.
+.TP
+.B NOTMUCH_CONFIG
+Specifies the location of the notmuch configuration file. Notmuch will
+use ${HOME}/.notmuch\-config if this variable is not set.
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-count\fR(1),