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> Compress the output in a format compatible with <b>gzip</b>(1).
  26
  27        <b>--format=(sup|batch-tag)</b>
  28               Notmuch  restore supports two plain text dump formats, both with
  29               one message-id per line, followed by a list of tags.
  30
  31               <b>batch-tag</b>
  32                      The default <b>batch-tag</b> dump format  is  intended  to  more
  33                      robust  against malformed message-ids and tags containing
  34                      whitespace or non-<b>ascii</b>(7) characters. Each line has  the
  35                      form
  36                         +&lt;<u>encoded-tag</u>&gt;  +&lt;<u>encoded-tag</u>&gt;  ... -- id:&lt;<u>quoted-mes‐</u>
  37                         <u>sage-id</u>&gt;
  38
  39                      Tags are hex-encoded by replacing every byte not matching
  40                      the regex <b>[A-Za-z0-9@=.,</b>_<b>+-]</b> with <b>%nn</b> where nn is the two
  41                      digit hex encoding. The message  ID  is  a  valid  Xapian
  42                      query, quoted using Xapian boolean term quoting rules: if
  43                      the ID contains whitespace or a  close  paren  or  starts
  44                      with a double quote, it must be enclosed in double quotes
  45                      and double quotes inside the  ID  must  be  doubled.  The
  46                      astute  reader  will notice this is a special case of the
  47                      batch input format for <a href='../notmuch-tag-1/'>notmuch-tag</a>(1); note that the sin‐
  48                      gle message-id query is mandatory for <a href='../notmuch-restore-1/'>notmuch-restore</a>(1).
  49
  50               <b>sup</b>    The  <b>sup</b>  dump  file  format is specifically chosen to be
  51                      compatible with the format of files produced by sup-dump.
  52                      So if you&apos;ve previously been using sup for mail, then the
  53                      <b>notmuch</b> <b>restore</b> command provides you a way to import  all
  54                      of your tags (or labels as sup calls them). Each line has
  55                      the following form
  56                         &lt;<u>message-id</u>&gt; <b>(</b> &lt;<u>tag</u>&gt; ... <b>)</b>
  57
  58                      with zero or more tags are separated by spaces. Note that
  59                      (malformed)  message-ids  may  contain arbitrary non-null
  60                      characters. Note also that tags with spaces will  not  be
  61                      correctly restored with this format.
  62
  63               With  no  search  terms,  a dump of all messages in the database
  64               will be generated. A &quot;--&quot; argument instructs  notmuch  that  the
  65               remaining arguments are search terms.
  66
  67               See  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax
  68               for &lt;search-terms&gt;.
  69 </pre>
  70
  71 <h2>SEE ALSO</h2>
  72 <pre>
  73        <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>
  74        <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),
  75        <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>
  76        <a href='../notmuch-tag-1/'>much-tag</a>(1)
  77 </pre>
  78
  79 <h2>AUTHOR</h2>
  80 <pre>
  81        Carl Worth and many others
  82 </pre>
  83
  84 <h2>COPYRIGHT</h2>
  85 <pre>
  86        2014, Carl Worth and many others
  87 </pre>
  88
  89 <h2>0.19</h2>