X-Git-Url: https://git.cworth.org/git?p=notmuch-wiki;a=blobdiff_plain;f=bugs.mdwn;h=d2b743fa4f6d01acb1696bc1ca2ce12bb2c89c27;hp=e9cd89c63c0c43d7aa10e497e46b5602d7f46728;hb=HEAD;hpb=841fd6493f9fede3e3ea6fefabfe5e80a4b1b77f

diff --git a/bugs.mdwn b/bugs.mdwn
index e9cd89c..d2b743f 100644
--- a/bugs.mdwn
+++ b/bugs.mdwn
@@ -1,5 +1,7 @@
 [[!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
 
@@ -9,6 +11,14 @@ search" or "notmuch show"; it's easier for us to debug if the problem
 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
@@ -34,7 +44,25 @@ If you submit lots of bugs and/or patches, you may want become
 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.