git.cworth.org Git - notmuch-wiki/blob - manpages/notmuch-dump-1.mdwn

   1 <h1>NOTMUCH-DUMP(1)</h1>
   2
   3 <h2>NAME</h2>
   4 <pre>
   5        notmuch-dump - creates a plain-text dump of the tags of each message
   6 </pre>
   7
   8 <h2>SYNOPSIS</h2>
   9 <pre>
  10        <b>notmuch</b>  <b>dump</b>  [--format=(batch-tag|sup)]  [--]  [--output=&lt;<u>file</u>&gt;] [--]
  11        [&lt;<u>search-term</u>&gt; ...]
  12 </pre>
  13
  14 <h2>DESCRIPTION</h2>
  15 <pre>
  16        Dump tags for messages matching the given search terms.
  17
  18        Output is to the given filename, if any, or to stdout.
  19
  20        These tags are the only data in the  notmuch  database  that  can&apos;t  be
  21        recreated  from  the messages themselves. The output of notmuch dump is
  22        therefore the only critical thing to backup (and much more friendly  to
  23        incremental backup than the native database files.)
  24
  25        <b>--gzip</b>
  26
  27               Compress the output in a format compatible with <b>gzip</b>(1).
  28
  29        <b>--format=(sup|batch-tag)</b>
  30
  31               Notmuch  restore supports two plain text dump formats, both with
  32               one message-id per line, followed by a list of tags.
  33
  34               <b>batch-tag</b>
  35
  36                      The default <b>batch-tag</b> dump format  is  intended  to  more
  37                      robust  against malformed message-ids and tags containing
  38                      whitespace or non-<b>ascii</b>(7) characters. Each line has  the
  39                      form
  40
  41                          +&lt;<u>encoded-tag</u>&gt;  +&lt;<u>encoded-tag</u>&gt; ... -- id:&lt;<u>quoted-mes-</u>
  42                          <u>sage-id</u>&gt;
  43
  44                      Tags are hex-encoded by replacing every byte not matching
  45                      the regex <b>[A-Za-z0-9@=.,</b>_<b>+-]</b> with <b>%nn</b> where nn is the two
  46                      digit hex encoding. The message  ID  is  a  valid  Xapian
  47                      query, quoted using Xapian boolean term quoting rules: if
  48                      the ID contains whitespace or a  close  paren  or  starts
  49                      with a double quote, it must be enclosed in double quotes
  50                      and double quotes inside the  ID  must  be  doubled.  The
  51                      astute  reader  will notice this is a special case of the
  52                      batch input format for <a href='../notmuch-tag-1/'>notmuch-tag</a>(1); note that the sin-
  53                      gle message-id query is mandatory for <a href='../notmuch-restore-1/'>notmuch-restore</a>(1).
  54
  55               <b>sup</b>
  56
  57                      The <b>sup</b> dump file format is  specifically  chosen  to  be
  58                      compatible with the format of files produced by sup-dump.
  59                      So if you&apos;ve previously been using sup for mail, then the
  60                      <b>notmuch</b>  <b>restore</b> command provides you a way to import all
  61                      of your tags (or labels as sup calls them). Each line has
  62                      the following form
  63
  64                          &lt;<u>message-id</u>&gt; <b>(</b> &lt;<u>tag</u>&gt; ... <b>)</b>
  65
  66                      with zero or more tags are separated by spaces. Note that
  67                      (malformed) message-ids may  contain  arbitrary  non-null
  68                      characters.  Note  also that tags with spaces will not be
  69                      correctly restored with this format.
  70
  71               With no search terms, a dump of all  messages  in  the  database
  72               will  be  generated.  A &quot;--&quot; argument instructs notmuch that the
  73               remaining arguments are search terms.
  74
  75               See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported  syntax
  76               for &lt;search-terms&gt;.
  77 </pre>
  78
  79 <h2>SEE ALSO</h2>
  80 <pre>
  81        <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-insert-1/'>not-</a>
  82        <a href='../notmuch-insert-1/'>much-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),
  83        <a href='../notmuch-search-1/'>notmuch-search</a>(1),   <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),   <a href='../notmuch-show-1/'>notmuch-show</a>(1),   <a href='../notmuch-tag-1/'>not-</a>
  84        <a href='../notmuch-tag-1/'>much-tag</a>(1)
  85 </pre>
  86
  87 <h2>AUTHOR</h2>
  88 <pre>
  89        Carl Worth and many others
  90 </pre>
  91
  92 <h2>COPYRIGHT</h2>
  93 <pre>
  94        2014, Carl Worth and many others
  95 </pre>
  96
  97 <h2>0.18</h2>