debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-24 20:08:10 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: bring notmuch-dump manual page in line with the rest

Browse source 
Fix indentation of options. Move search terms description before
options. Fix synopsis.
This commit is contained in:
Jani Nikula 2015-01-27 21:48:14 +02:00 committed by David Bremner
parent 625401eb2f
commit 6cc1c8d149
1 changed files with 44 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
doc/man1/notmuch-dump.rst
View file

@ -5,7 +5,7 @@ notmuch-dump
SYNOPSIS SYNOPSIS
======== ========
**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...] **notmuch** **dump** [--gzip] [--format=(batch-tag|sup)] [--output=<*file*>] [--] [<*search-term*> ...]
DESCRIPTION DESCRIPTION
=========== ===========
@ -19,52 +19,58 @@ recreated from the messages themselves. The output of notmuch dump is
therefore the only critical thing to backup (and much more friendly to therefore the only critical thing to backup (and much more friendly to
incremental backup than the native database files.) incremental backup than the native database files.)
``--gzip`` See **notmuch-search-terms(7)** for details of the supported syntax
Compress the output in a format compatible with **gzip(1)**. for <search-terms>. 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.
``--format=(sup|batch-tag)`` Supported options for **dump** include
Notmuch restore supports two plain text dump formats, both with one
message-id per line, followed by a list of tags.
**batch-tag** ``--gzip``
The default **batch-tag** dump format is intended to more robust Compress the output in a format compatible with **gzip(1)**.
against malformed message-ids and tags containing whitespace or
non-\ **ascii(7)** characters. Each line has the form
+<*encoded-tag*\ > +<*encoded-tag*\ > ... -- ``--format=(sup|batch-tag)``
id:<*quoted-message-id*\ > Notmuch restore supports two plain text dump formats, both with one
message-id per line, followed by a list of tags.
Tags are hex-encoded by replacing every byte not matching the **batch-tag**
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 default **batch-tag** dump format is intended to more
The **sup** dump file format is specifically chosen to be robust against malformed message-ids and tags containing
compatible with the format of files produced by sup-dump. So if whitespace or non-\ **ascii(7)** characters. Each line has
you've previously been using sup for mail, then the **notmuch the form
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*\ > ... **)** +<*encoded-tag*\ > +<*encoded-tag*\ > ... --
id:<*quoted-message-id*\ >
with zero or more tags are separated by spaces. Note that Tags are hex-encoded by replacing every byte not matching
(malformed) message-ids may contain arbitrary non-null the regex **[A-Za-z0-9@=.,\_+-]** with **%nn** where nn is
characters. Note also that tags with spaces will not be the two digit hex encoding. The message ID is a valid
correctly restored with this format. 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)**.
With no search terms, a dump of all messages in the database will be **sup**
generated. A "--" argument instructs notmuch that the remaining
arguments are search terms. 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.
See **notmuch-search-terms(7)** for details of the supported syntax
for <search-terms>.
SEE ALSO SEE ALSO
======== ========