[[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
-# Troubleshooting and Bug reporting
+# Troubleshooting and Bug Reporting
+
+[[!toc levels=2]]
## Deciding what level the problem lives at
is there, and it's useful to know if the problem is introduced by a
front end.
+## Understanding the structure of a problematic message
+
+The script
+[print-mime-structure](https://git.spwhitton.name/mailscripts/plain/email-print-mime-structure)
+prints out the mime structure of an email message as a (text)
+tree. This is usually safe to share and can help people understand
+your problem.
+
## Troubleshooting the Emacs interface
It's very easy for Emacs packages to interfere with each other. For
involved with this tagging process, but feel free to just send mail to
the list; someone will tag messages appropriately. The status of bugs
and current patches can also be followed
-[online](http://nmbug.notmuchmail.org/status).
+[online](https://nmbug.notmuchmail.org/status).
+
+## Debugging Queries
+
+If a search doesn't seem to do what you want, you can enable query debugging to
+print the Xapian queries the Notmuch library constructs by setting the
+`NOTMUCH_DEBUG_QUERY` environment variable to a non-empty value.
+
+For example:
+
+ $ NOTMUCH_DEBUG_QUERY=1 notmuch search big brown fox
+ Query string is:
+ big brown fox
+ Exclude query is:
+ Xapian::Query()
+ Final query is:
+ Xapian::Query((Tmail AND Zbig:(pos=1) AND Zbrown:(pos=2) AND Zfox:(pos=3)))
+## Rescuing your tags.
+If you're database is corrupt and you don't have a backup, a modified version of [xapian-check](https://git.xapian.org/?p=xapian;a=blob;f=README.notmuch;hb=refs/heads/notmuch-tag-rescue-hack) might still save your tags.