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

   1 <h1>NOTMUCH-TAG(1)</h1>
   2
   3 <h2>NAME</h2>
   4 <pre>
   5        notmuch-tag  -  add/remove  tags  for  all messages matching the search
   6        terms
   7 </pre>
   8
   9 <h2>SYNOPSIS</h2>
  10 <pre>
  11        <b>notmuch</b> <b>tag</b> [<u>options</u>...] +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>search-term</u>&gt; [...]
  12
  13        <b>notmuch</b> <b>tag</b> --batch [ --input=&lt;<u>filename</u>&gt; ]
  14 </pre>
  15
  16 <h2>DESCRIPTION</h2>
  17 <pre>
  18        Add/remove tags for all messages matching the search terms.
  19
  20        See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
  21        &lt;<u>search-term</u>&gt;.
  22
  23        Tags prefixed by &apos;+&apos; are added while those prefixed by &apos;-&apos; are removed.
  24        For each message, tag changes are applied in the order they  appear  on
  25        the command line.
  26
  27        The  beginning  of the search terms is recognized by the first argument
  28        that begins with neither &apos;+&apos; nor &apos;-&apos;. Support  for  an  initial  search
  29        term  beginning  with  &apos;+&apos;  or  &apos;-&apos; is provided by allowing the user to
  30        specify a &quot;--&quot; argument to separate the tags from the search terms.
  31
  32        <b>notmuch</b> <b>tag</b> updates the maildir flags according to tag changes  if  the
  33        <b>maildir.synchronize</b>_<b>flags</b> configuration option is enabled. See <a href='../notmuch-config-1/'>notmuch-</a>
  34        <a href='../notmuch-config-1/'>config</a>(1) for details.
  35
  36        Supported options for <b>tag</b> include
  37
  38            <b>--remove-all</b>
  39
  40                Remove all tags from each message  matching  the  search  terms
  41                before  applying the tag changes appearing on the command line.
  42                This means setting the tags of each message to the tags  to  be
  43                added. If there are no tags to be added, the messages will have
  44                no tags.
  45
  46            <b>--batch</b>
  47
  48                Read batch tagging operations from a file (stdin  by  default).
  49                This  is  more efficient than repeated <b>notmuch</b> <b>tag</b> invocations.
  50                See <b>TAG</b> <b>FILE</b> <b>FORMAT</b> below for the input format. This option  is
  51                not compatible with specifying tagging on the command line.
  52
  53            <b>--input=</b>&lt;filename&gt;
  54
  55                Read  input  from  given  file,  instead of from stdin. Implies
  56                <b>--batch</b>.
  57 </pre>
  58
  59 <h2>TAG FILE FORMAT</h2>
  60 <pre>
  61        The input must consist of lines of the format:
  62
  63        +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>query</u>&gt;
  64
  65        Each  line  is  interpreted  similarly  to  <b>notmuch</b>  <b>tag</b>  command  line
  66        arguments.  The  delimiter is one or more spaces &apos; &apos;. Any characters in
  67        &lt;<u>tag</u>&gt; <b>may</b> be hex-encoded with %NN where NN is the hexadecimal value  of
  68        the character. To hex-encode a character with a multi-byte UTF-8 encod-
  69        ing, hex-encode each byte.  Any spaces in &lt;tag&gt; <b>must</b> be hex-encoded  as
  70        %20. Any characters that are not part of &lt;<u>tag</u>&gt; <b>must</b> <b>not</b> be hex-encoded.
  71
  72        In the future tag:&quot;tag with spaces&quot; style quoting may be supported  for
  73        &lt;<u>tag</u>&gt;  as  well;  for  this reason all double quote characters in &lt;<u>tag</u>&gt;
  74        <b>should</b> be hex-encoded.
  75
  76        The &lt;<u>query</u>&gt; should be quoted using Xapian boolean term  quoting  rules:
  77        if  a term contains whitespace or a close paren or starts with a double
  78        quote, it must be enclosed in double quotes (not including any  prefix)
  79        and  double quotes inside the term must be doubled (see below for exam-
  80        ples).
  81
  82        Leading and trailing space &apos; &apos; is ignored. Empty lines and lines begin-
  83        ning with &apos;#&apos; are ignored.
  84 </pre>
  85
  86 <h3> &nbsp; EXAMPLE</h3>
  87 <pre>
  88        The  following shows a valid input to batch tagging. Note that only the
  89        isolated &apos;*&apos; acts as a wildcard. Also note the two  different  quotings
  90        of the tag <b>space</b> <b>in</b> <b>tags</b>
  91               +winner *
  92               +foo::bar%25 -- (One and Two) or (One and tag:winner)
  93               +found::it -- tag:foo::bar%
  94               # ignore this line and the next
  95
  96               +space%20in%20tags -- Two
  97               # add tag &apos;(tags)&apos;, among other stunts.
  98               +crazy{ +(tags) +&amp;are +#possible -- tag:&quot;space in tags&quot;
  99               +match*crazy -- tag:crazy{
 100               +some_tag -- id:&quot;this is &quot;&quot;nauty)&quot;&quot;&quot;
 101 </pre>
 102
 103 <h2>SEE ALSO</h2>
 104 <pre>
 105        <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-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a>
 106        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),   <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
 107        <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <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/'>not-</a>
 108        <a href='../notmuch-show-1/'>much-show</a>(1),
 109 </pre>
 110
 111 <h2>Notmuch 0.17</h2>