NOTMUCH-TAG(1)

📦
version 0.40 · 13 versions
, in fedora 44, nixos 26.05, ubuntu resolute

💖 NOTMUCH-TAG 💖

okay bestie, buckle up, we're tagging mail like it's going out of style ✨ this is the manual page for notmuch-tag, part of the notmuch fam.

🌸 NAME 🌸

notmuch-tag — add/remove tags for all messages matching the search terms 🏷️💅

✨ SYNOPSIS ✨

notmuch tag [options ...] +<tag>|-<tag> [--] <search-term> ...

notmuch tag --batch [--input=<filename>]

🦋 DESCRIPTION 🦋

So basically: this adds and/or removes tags on every single message that matches your search terms. Slay.

Wanna know what search syntax you can use in <search-term>? Go look at notmuch-search-terms — it's all there, iykyk. 🎀

Tags with a + in front get added, tags with a - in front get removed. And for each message, the tag changes happen in the exact order they show up on the command line. Order matters, periodt.

Now, how does notmuch know where your search terms start? It's the first argument that starts with neither + nor -. But what if your search term literally starts with a + or -?? 😭 No worries — you're allowed to drop a -- argument in there to separate the tags from the search terms. Iconic.

Also important: notmuch tag updates the maildir flags to match your tag changes if the maildir.synchronize_flags configuration option is enabled. Details over in notmuch-config. 👑

Supported options for tag include:

  • --remove-all — wipe all the tags off every matching message before applying the tag changes from the command line. So basically you're setting each message's tags to just the tags you're adding. And if you're adding nothing? Congrats, those messages end up with zero tags. 💀
  • --batch — read a whole pile of tagging operations from a file (stdin by default). This is way more efficient than calling notmuch tag over and over again. Input format lives in TAG FILE FORMAT down below. 🫶 Warning: this option is not compatible with specifying tagging on the command line.
  • --input=<filename> — read input from the file you name instead of stdin. This one implies --batch. 🌈

🎀 TAG FILE FORMAT 🎀

Your input has to be lines that look like this:

+<tag>|-<tag> [...] [--] <query>

Every line gets interpreted kinda the same way notmuch tag command line arguments do. The delimiter is one or more spaces ' '. 🍓

Any characters in <tag> can be hex-encoded with %NN, where NN is the hexadecimal value of the character. Got a character with a multi-byte UTF-8 encoding? Hex-encode each byte. Any spaces in <tag> must be hex-encoded as %20. And any characters that are not part of <tag> must not be hex-encoded. No cap.

Heads up for the future: tag:"tag with spaces" style quoting may be supported for <tag> someday too. Which is exactly why all double quote characters in <tag> should be hex-encoded. Prep now, thank yourself later. ✨

The <query> should be quoted using Xapian boolean term quoting rules: if a term contains whitespace, or a close paren, or starts with a double quote, it must be enclosed in double quotes (not including any prefix) and double quotes inside the term must be doubled. Examples below, bestie 👇

Leading and trailing space ' ' gets ignored. Empty lines and lines starting with # get ignored too. 🙈

💅 EXAMPLE 💅

Here's a valid input for batch tagging. Note that only the isolated '*' acts as a wildcard. Also note the two different quotings of the tag space in tags:

+winner *
+foo::bar%25 -- (One and Two) or (One and tag:winner)
+found::it -- tag:foo::bar%
# ignore this line and the next

+space%20in%20tags -- Two
# add tag '(tags)', among other stunts.
+crazy{ +(tags) +&are +#possible\ -- tag:"space in tags"
+match*crazy -- tag:crazy{
+some_tag -- id:"this is ""nauty)"""

🌈 SEE ALSO 🌈

  • notmuch
  • notmuch-config
  • notmuch-count
  • notmuch-dump
  • notmuch-hooks
  • notmuch-insert
  • notmuch-new
  • notmuch-reply
  • notmuch-restore
  • notmuch-search
  • notmuch-search-terms
  • notmuch-show

👑 AUTHOR 👑

Carl Worth and many others 🫶 (a whole squad fr fr)

2009-2026, Carl Worth and many others

okay that's the whole page, you're officially a tagging girlie now 💖 version 0.40, dated Jan 31, 2026 — go forth and tag, bestie, you've got this 🌸🦋✨

📦 where this page comes from