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