X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-dump.rst;h=ec6335b2febc97099249c01c02002cf6044192f6;hb=HEAD;hp=17d1da5c7d0884f67dcc8ad2280b6157a453f39f;hpb=d736260385a689b5c77d8121f48e29440e3adfa4;p=notmuch diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst index 17d1da5c..a7ca39d0 100644 --- a/doc/man1/notmuch-dump.rst +++ b/doc/man1/notmuch-dump.rst @@ -1,3 +1,5 @@ +.. _notmuch-dump(1): + ============ notmuch-dump ============ @@ -5,7 +7,7 @@ notmuch-dump SYNOPSIS ======== -**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...] +**notmuch** **dump** [--gzip] [--format=(batch-tag|sup)] [--output=<*file*>] [--] [<*search-term*> ...] DESCRIPTION =========== @@ -19,54 +21,103 @@ recreated from the messages themselves. The output of notmuch dump is therefore the only critical thing to backup (and much more friendly to incremental backup than the native database files.) -``--format=(sup|batch-tag)`` - Notmuch restore supports two plain text dump formats, both with one - message-id per line, followed by a list of tags. - - **batch-tag** - The default **batch-tag** dump format is intended to more robust - against malformed message-ids and tags containing whitespace or - non-\ **ascii(7)** characters. Each line has the form - - +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- - id:<*quoted-message-id*\ > - - Tags are hex-encoded by replacing every byte not matching the - regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two - digit hex encoding. The message ID is a valid Xapian query, - quoted using Xapian boolean term quoting rules: if the ID - contains whitespace or a close paren or starts with a double - quote, it must be enclosed in double quotes and double quotes - inside the ID must be doubled. The astute reader will notice - this is a special case of the batch input format for - **notmuch-tag(1)**; note that the single message-id query is - mandatory for **notmuch-restore(1)**. - - **sup** - The **sup** dump file format is specifically chosen to be - compatible with the format of files produced by sup-dump. So if - you've previously been using sup for mail, then the **notmuch - restore** command provides you a way to import all of your tags - (or labels as sup calls them). Each line has the following form - - <*message-id*\ > **(** <*tag*\ > ... **)** - - with zero or more tags are separated by spaces. Note that - (malformed) message-ids may contain arbitrary non-null - characters. Note also that tags with spaces will not be - correctly restored with this format. - - With no search terms, a dump of all messages in the database will be - generated. A "--" argument instructs notmuch that the remaining - arguments are search terms. - - See **notmuch-search-terms(7)** for details of the supported syntax - for . +See :any:`notmuch-search-terms(7)` for details of the supported syntax +for . With no search terms, a dump of all messages in +the database will be generated. A ``--`` argument instructs notmuch that +the remaining arguments are search terms. + +Supported options for **dump** include + +.. program:: dump + +.. option:: --gzip + + Compress the output in a format compatible with :manpage:`gzip(1)`. + +.. option:: --format=(sup|batch-tag) + + Notmuch restore supports two plain text dump formats, both with + one message-id per line, followed by a list of tags. + + batch-tag + The default **batch-tag** dump format is intended to more + robust against malformed message-ids and tags containing + whitespace or non-\ :manpage:`ascii(7)` characters. Each line + has the form:: + + +<*encoded-tag*\ > +<*encoded-tag*\ > ... -- id:<*quoted-message-id*\ > + + Tags are hex-encoded by replacing every byte not matching the + regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is the two + digit hex encoding. The message ID is a valid Xapian query, + quoted using Xapian boolean term quoting rules: if the ID + contains whitespace or a close paren or starts with a double + quote, it must be enclosed in double quotes and double quotes + inside the ID must be doubled. The astute reader will notice + this is a special case of the batch input format for + :any:`notmuch-tag(1)`; note that the single message-id query is + mandatory for :any:`notmuch-restore(1)`. + + sup + The **sup** dump file format is specifically chosen to be + compatible with the format of files produced by + :manpage:`sup-dump(1)`. So if you've previously been using sup + for mail, then the :any:`notmuch-restore(1)` command provides + you a way to import all of your tags (or labels as sup calls + them). Each line has the following form:: + + <*message-id*\ > **(** <*tag*\ > ... **)** + + with zero or more tags are separated by spaces. Note that + (malformed) message-ids may contain arbitrary non-null + characters. Note also that tags with spaces will not be + correctly restored with this format. + +.. option:: --include=(config|properties|tags) + + Control what kind of metadata is included in the output. + + config + Output configuration data stored in the database. Each line + starts with "#@ ", followed by a space separated key-value + pair. Both key and value are hex encoded if needed. + + properties + Output per-message (key,value) metadata. Each line starts + with "#= ", followed by a message id, and a space separated + list of key=value pairs. Ids, keys and values are hex encoded + if needed. See :any:`notmuch-properties(7)` for more details. + + tags + Output per-message boolean metadata, namely tags. See *format* above + for description of the output. + + The default is to include all available types of data. The option + can be specified multiple times to select some subset. As of + version 3 of the dump format, there is a header line of the + following form:: + + #notmuch-dump <*format*>:<*version*> <*included*> + + where <*included*> is a comma separated list of the above options. + +.. option:: --output= + + Write output to given file instead of stdout. SEE ALSO ======== -**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**, -**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**, -**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**, -**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)** +:any:`notmuch(1)`, +:any:`notmuch-config(1)`, +:any:`notmuch-count(1)`, +:any:`notmuch-hooks(5)`, +:any:`notmuch-insert(1)`, +:any:`notmuch-new(1)`, +:any:`notmuch-properties(7)`, +: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)`