lib: API to retrieve database revision and UUID

This exposes the committed database revision to library users along
with a UUID that can be used to detect when revision numbers are no
longer comparable (e.g., because the database has been replaced).

lib: Add per-message last modification tracking

This adds a new document value that stores the revision of the last
modification to message metadata, where the revision number increases
monotonically with each database commit.

An alternative would be to store the wall-clock time of the last
modification of each message.  In principle this is simpler and has
the advantage that any process can determine the current timestamp
without support from libnotmuch.  However, even assuming a computer's
clock never goes backward and ignoring clock skew in networked
environments, this has a fatal flaw.  Xapian uses (optimistic)
snapshot isolation, which means reads can be concurrent with writes.
Given this, consider the following time line with a write and two read
transactions:

   write  |-X-A--------------|
   read 1       |---B---|
   read 2                      |---|

The write transaction modifies message X and records the wall-clock
time of the modification at A.  The writer hangs around for a while
and later commits its change.  Read 1 is concurrent with the write, so
it doesn't see the change to X.  It does some query and records the
wall-clock time of its results at B.  Transaction read 2 later starts
after the write commits and queries for changes since wall-clock time
B (say the reads are performing an incremental backup).  Even though
read 1 could not see the change to X, read 2 is told (correctly) that
X has not changed since B, the time of the last read.  In fact, X
changed before wall-clock time A, but the change was not visible until
*after* wall-clock time B, so read 2 misses the change to X.

This is tricky to solve in full-blown snapshot isolation, but because
Xapian serializes writes, we can use a simple, monotonically
increasing database revision number.  Furthermore, maintaining this
revision number requires no more IO than a wall-clock time solution
because Xapian already maintains statistics on the upper (and lower)
bound of each value stream.

configure: clean up messages around reading libnotmuch version

Clean up punctuation for consistency, and add newline for clean
configure output.

build: extract library versions from notmuch.h

- Make lib/notmuch.h the canonical location for the library versioning
information.

- Since the release-check should never fail now, remove it to reduce
complexity.

- Make the version numbers in notmuch.h consistent with the (now
  deleted) ones in lib/Makefile.local

test: make script exit (1) if it "fails" to source (.) a file

The files (test) scripts source (with builtin command `.`) provides
information which the scripts depend, and without the `source` to
succeed allowing script to continue may lead to dangerous situations
(e.g. rm -rf "${undefined_variable}"/*).

At the end of all source (.) lines construct ' || exit 1' was added;
In our case the script script will exit if it cannot find (or read) the
file to be sourced. Additionally script would also exits if the last
command of the sourced file exited nonzero.

NEWS: emacs: notmuch-{cli,emacs}-version usage

News for notmuch-emacs-version usage in User-Agent header and
rename of function notmuch-version to notmuch-cli-version.

While at it, made some minor (consistency) punctuation changes
to make news to wiki conversion work as expected.

emacs/notmuch-mua.el: whitespace cleanup

M-x whitespace-cleanup in Emacs.

emacs: make modifications to message Fcc vars buffer-local

Previously we globally modified these variables, which tended to cause
problems for people using message-mode, but not notmuch-mua-mail, to
send mail.

User visible changes:

- Calling notmuch-fcc-header-setup is no longer optional. OTOH, it
  seems to do the right thing if notmuch-fcc-dirs is set to nil.

- The Fcc header is visible during message composition

- The name in the mode line is changed, and no longer matches exactly
  the menu label.

- Previously notmuch-mua-send-and-exit was never called.  Either we
  misunderstood define-mail-user-agent, or it had a bug.  So there was
  no difference if the user called message-send-and-exit directly. Now
  there will be.

- User bindings to C-c C-c and C-c C-s in message-mode-map are
  overridden. The user can override them in notmuch-message-mode-map,
  but then they're on their own for Fcc handling.

emacs: define a notmuch-compose-mode based on message mode.

This is to provide a clean way of overriding e.g. keybindings when
sending mail from notmuch.

This is needed in particular to allow somewhere to dynamically bind
certain message-mode variables which are not respected when buffer-local. See e.g.

     http://debbugs.gnu.org/cgi/bugreport.cgi?bug=21174

test: add debugging output to notmuch-new tests, mark 5 as broken

I marked the tests where I really couldn't understand the output as
broken. It could also be that I don't understand how directory removal
is supposed to work.

cli/new: add more debugging output

Try to narrow down what part of the code adds files and directories to
the queue(s) to be deleted.

Update one test. The output is slightly confusing, but I believe it is
correct, resulting from a directory being discovered but containing only ignored files.

test: don't claim single message mbox support is going away

We gave up on this.

emacs: prefer notmuch-emacs-version in User-Agent: header

Now that we have `notmuch-emacs-version' defined in notmuch emacs MUA
use that as a part of User-Agent: header to provide more accurate
version information when sending emails.

In case some incomplete installation of notmuch emacs MUA is used and
`notmuch-emacs-version' is defined as "unknown" then fall back to ask
version info from cli (as it used to be before this commit).

Requiring notmuch-version[.elc] and if that is missing setting
"fallback" notmuch-emacs-version (to "unknown") was moved from
notmuch.el to notmuch-lib.el as notmuch-mua.el (which provides
User-Agent: information) require's the latter.

emacs: renamed function notmuch-version to notmuch-cli-version

As it asks `notmuch` binary for its version number.

devel/release-checks.sh: made python version check work with python 3

This trivial change consists of just putting print() argument in
parentheses.

test: use the python interpreter in sh.config

The configure script chooses "python" if both python and python{2,3}
exist exists, so this could change the version of python used to run
the test suite.

The checking for ${NOTMUCH_PYTHON} in the test suite is arguably
over-engineering, since the configure step will fail if it can't find
it.

emacs: add a filter option to show

Show the current thread with a different filter (i.e., open messages
in the thread matching the new query).

Bound to 'l' for "limit".

Note that it is not the same as filter in search mode as it replaces
the existing query rather than ANDing with it (but it does keep the
thread-id part of the query).

emacs: split notmuch-show-apply-state

Separate out a notmuch-show-goto-msg-id sub-function from
notmuch-show-apply-state. There should be no functional change but the
next patch will call the new function.

lib: add public accessor for database from query

This is to make it easier for clients of the library to update to the
new error code returning versions of notmuch_query_search_messages

lib: deprecate notmuch_query_search_{threads, messages}

The CLI (and bindings) code should really be updated to use the new
status-code-returning versions. Here are some warnings to prod us (and
other clients) to do so.

lib: define NOTMUCH_DEPRECATED macro, document its use.

This has been tested with gcc and clang.

lib: Only sync modified message documents

Previously, we updated the database copy of a message on every call to
_notmuch_message_sync, even if nothing had changed.  In particular,
this always happens on a thaw, so a freeze/thaw pair with no
modifications between still caused a database update.

We only modify message documents in a handful of places, so keep track
of whether the document has been modified and only sync it when
necessary.  This will be particularly important when we add message
revision tracking.

configure: support --without-ruby

Apparently some ruby installs are broken in ways that prevent the ruby
bindings from building.

configure: support --with-docs=no

Since we promise --with-foo=no is equivalent to --without-foo

configure: alphabetize --without help

Now that the "without" options seem to be multiplying, try to make it
easier for people to find the one they want.

configure: fix typo in comment

Some lazy person, probably me, forgot to press shift.

cli: enable notmuch --help command

This functionality seems to have been undocumented, if it ever
existed. Document it now.

doc: whitespace cleanup for notmuch.rst

replace leading spaces with tabs

build: add "set -eu" to version script generation

It turns out that on certain systems like FreeBSD, c++filt is not
installed by default. It's basically OK if we fail the build in that
case, but what's really not OK is for the build to continue and
generate bad binaries.

configure: whitespace cleanup

This is the result of running M-x whitespace-cleanup in emacs.  In
particular this replaces some spaces at the beginning of lines with
tabs.

configure: add --without-docs switch

Previously documentation was build automatically if sphinx/doxygen
executable were found. The switch is used to unconditionally disable
sphinx/doxygen detection and therefor, building of documentation
(including man pages).

replace hardcoded "python" with configured python command

Thanks to FreeBSD port maintainer Mikhail for report and the original
the original patch.

This is the right thing (TM) and also apparently fixes the build on
FreeBSD.

Fix documentation for notmuch--tag-hook functions

The second argument to notmuch-tag is now called tag-changes, but the
documentation for notmuch-before-tag-hook and notmuch-after-tag-hook
still used the old argument name `tags'. This resulted in broken hooks
when following the documentation.

Merge tag '0.20.2'

notmuch 0.20.2 release

Conflicts:
NEWS

version: update to 0.20.2

As usual, bump python version at same time.

debian: update changelog for 20.2-1

Actual changes are documented in the bug.

NEWS for 0.20.2

Just the one bug fix

emacs: tree: mark read change

The mark read code for tree mode did not get updated in the recent
changes. This updates it to match. Since the user can customize the
mark read logic we just call the show logic in the message pane.

test: add initial ruby tests

This is pretty much a line by line translation of the existing python
tests, with two new tests for the count API.

build/ruby: use notmuch configure script values for shared lib

This is supposed to help build on systems like MacOS with different
conventions for naming shared libraries. We have already computed the
relevant names, so doing it again in ruby seems like a bad idea.

lib, ruby: make use of -Wl,--no-undefined configurable

In particular this is supposed to help build on systems (presumably
using a non-gnu ld) where this flag is not available.

emacs search: stash query

Add keybinding c q to stash the current query in search mode.

build: integrate building ruby bindings into notmuch build process

Because ruby generates a Makefile, we have to use recursive make.
Because mkmf.rb hardcodes the name Makefile, put our Makefile{.local}
in the parent directory.

lib: reject relative paths in n_d_{create,open}_verbose

There are many places in the notmuch code where the path is assumed to be absolute. If someone (TM) wants a project, one could remove these assumptions. In the mean time, prevent users from shooting themselves in the foot.

Update test suite mark tests for this error as no longer broken, and
also convert some tests that used relative paths for nonexistent
directories.

lib: add NOTMUCH_STATUS_PATH_ERROR

The difference with FILE_ERROR is that this is for things that are
wrong with the path before looking at the disk.

Add some 3 tests; two broken as a reminder to actually use this new
code.

release-checks: check that git working directory is clean

Before release check that there are no uncommitted changes and
that there are no files in working directory that possibly should
have been added to the repository.

Amended by db: remove --ignored, since that seems like too much
trouble.

test: redirect man output to /dev/null

In the case the these tests fail, they generate a bunch of output;
this output is not very interesting because it is just the successful
output of a man page. It does however make it hard to see what tests are actually failing, even with NOTMUCH_TEST_QUIET

configure: add ability to force python version via environment

This is makes it a bit easier to run our test suite under alternative
python versions.

test: make python tests compatible with python3

Making the test suite actually run them with python3 is left for
future work.

doc: add minimal note about shared options.

The example is a bit silly, but notmuch subcommand --help is actually
not equivalent to "notmuch --help subcommand".

Merge branch 'release'

20.1 plus NEWS fixup

NEWS: missing NEWS for 20.1

Embarrassingly, these were not included in the actual 20.1 release

debian: change stanza for 0.20.1

version: bump to 20.1

cli: add standard option processing to config, help and setup

In particular this fixes a recently encountered bug where the
"--config" argument to "notmuch setup" is silently ignored, which the
unpleasant consequence of overwriting the users config file.

cli: define shared options, use for --help and --version

Unfortunately it seems trickier to support --config globally

The non-trivial changes are in notmuch.c; most of the other changes
consists of blindly inserting two lines into every subcommand.

cli: refactor notmuch_help_command

Create a new private entry point _help_for so that we can call help
without simulating a command line invokation to set up the arguments.

cli: ignore config argument of notmuch_help_command

We call it with NULL at one point anyway, so it needs to work with
NULL. Since the only place we use talloc is right before exec, there
is no harm in always using NULL.

cli: change "setup" to "set up" where used as a verb

The word "setup" is a noun, not a verb.  Change occurrences of "setup"
where used as a verb to "set up".

emacs: Added "is:<tag>" style completion to notmuch-read-query.

The notmuch-search-terms man page states that "tag:<tag>" is equivalent
to "is:<tag>". Completion for "is:<tag>" style searches is now supported
in the Emacs interface.

Amended by David Bremner: combine lexical-let and let into
lexical-let*

test: remove redundant 'file' command from gdb scripts.

Quoting Debian bug 787341

   It failed to build on arm64: the last ten tests in T070-insert
   failed.

   What's happening here is that GDB is segfaulting in response to
   the
   "file" command. GDB on arm64 can be a bit buggy.

   However, the "file" command is redundant here as GDB has already
   got
   the file from the --args on the command line.

Merge tag '0.20'

notmuch 0.20 release

NEWS: bump date

debian: changelog stanza for 0.20-1

version: bump to 0.20

drop mention of notmuch-emacs-mua

Merge tag '0.20_rc2'

notmuch 0.20~rc2 release

debian: changelog stanza for 0.20~rc2-1

version: bump to 0.20~rc2

python: use absolute import for SOVERSION

Apparently python3 needs this.

docs: initial draft of NEWS for 0.20

This is meant as much to jog people's memory as to be definitive.

configure: Add sanity checking for environment variables

Passing in environment variables incompatible with the compiler may
cause other parts of the configure script to fail in hard to
understand ways, so we abort early.

Merge tag '0.20_rc1'

notmuch 0.20~rc1 release

debian: add new symbols to libnotmuch4.symbols

Since we only add new symbols, no SONAME bump is needed.

debian: call upstream configure script directly

dh defaults for dh_auto_configure are now incompatible with notmuch's
homebrew configure script (at least in debian experimental)

version: bump to 0.20~rc1

debian: changelog stanza for 0.20~rc1

notmuch-mutt: fix xargs/ln usage for OpenBSD compatibility

- xargs: use -r flag instead of --no-run-if-empty
- ln: use -I flag/3rd form of ln command instead of -t flag/4th form

Signed-off-by: Stefano Zacchiroli <zack@upsilon.cc>

test: move nonexistent directory to something under notmuch's control.

Apparently some systems actually have a directory called /nonexist[ae]nt.
It's hard to fathom a good reason for that, but oh well. As long as we
don't create such a directory inside the notmuch source tree, the new
version should be more robust.

test: be consistent about spelling `nonexistent'

Apparently most of the misspellings are my fault.

emacs: show: hide large text attachments by default

notmuch-show can be slow displaying large attachments so hide them by
default. The default maximum size is 10000 bytes/characters but it is
customizable.

Note that notmuch-show-insert-bodypart is also called from the reply
code so we need to be a little careful.

test/thread-order: more robust loop exit in case of broken input

When creating $THREADS data it may end of not having 'None' at all
or the numbers in line output yields a loop.

To avoid loop the value in current array index is set to 'None'
so that if the same item is reached again the loop will end.

Also empty string as next array index will end the loop.

notmuch-emacs-mua: non-forking escape () usage with backslash '\' escape

Use the printf -v convention to give output variable as argument
to escape () function so no subshell needs to be executed for
escaping input. The '-v' option to escape () is just syntactic
sugar for better understanding.

Also, backslash is now escaped with another backslash for emacs. This
ie especially important at the end of string.

`echo` is no longer used to write escaped output -- it might interpret
the escapes itself.

nmbug-status: Use 'show-ref --heads' for loading configs

When loading configs from Git, the bare branch name (without a
refs/heads/ prefix or similar) matches all branches of that name
(including remote-tracking branches):

  .nmbug $ git show-ref config
  48f3bbf1d1492e5f3d2f01de6ea79a30d3840f20 refs/heads/config
  48f3bbf1d1492e5f3d2f01de6ea79a30d3840f20 refs/remotes/origin/config
  4b6dbd9ffd152e7476f5101eff26747f34497cee refs/remotes/wking/config

Instead of relying on the ordering of the matching references, use
--heads to ensure we only match local branches.

NEWS: fix 'not' -> 'now' typo in 0.19 nmbug section

test: make one error output test more robust.

Since notmuch_database_status_string can return NULL, passing it
directly to fputs is not a good idea.

test: add more error reporting tests

This second half of the error reporting tests actually uses the function
notmuch_database_status_string to retrieve the last logged error

lib: eliminate fprintf from _notmuch_message_file_open

You may wonder why _notmuch_message_file_open_ctx has two parameters.
This is because we need sometime to use a ctx which is a
notmuch_message_t. While we could get the database from this, there is
no easy way in C to tell type we are getting.

lib: replace almost all fprintfs in library with _n_d_log

This is not supposed to change any functionality from an end user
point of view. Note that it will eliminate some output to stderr. The
query debugging output is left as is; it doesn't really fit with the
current primitive logging model. The remaining "bad" fprintf will need
an internal API change.

lib: add private function to extract the database for a message.

This is needed by logging in functions outside message.cc that take
only a notmuch_message_t object.

lib: add a log function with output to a string in notmuch_database_t

In principle in the future this could do something fancier than
asprintf.

lib: add "verbose" versions of notmuch_database_{open,create}

The compatibility wrapper ensures that clients calling
notmuch_database_open will receive consistent output for now.

The changes to notmuch-{new,search} and test/symbol-test are just to
make the test suite pass.

The use of IGNORE_RESULT is justified by two things. 1) I don't know
what else to do.  2) asprintf guarantees the output string is NULL if
an error occurs, so at least we are not passing garbage back.

test: add error reporting tests

This first half of the tests is all that don't need to retrieve the
the error string explicitly from the notmuch database structure.

test: add support for compiling and running C snippets

This is to limit the copy-pasta involved in running C tests. I decided
to keep things simple and not try to provide an actual C skeleton.

The setting of LD_LIBRARY_PATH is to force using the built libnotmuch
rather than any potential system one.

test: Add two tests for error output from notmuch_database_open

This is arguably testing the same thing twice, but in the brave new
future where we don't use printf anymore, each subcommand will be
responsible for handling the output on it's own.

nmbug-status: Clarify errors for illegible configs

Carl Worth pointed out that errors like:

  $ ./nmbug-status
  fatal: Not a git repository: '/home/cworth/.nmbug'
  fatal: Not a git repository: '/home/cworth/.nmbug'
  Traceback (most recent call last):
    File "./nmbug-status", line 254, in <module>
      config = read_config(path=args.config)
    File "./nmbug-status", line 73, in read_config
      return json.load(fp)
    File "/usr/lib/python2.7/json/__init__.py", line 290, in load
      **kw)
    File "/usr/lib/python2.7/json/__init__.py", line 338, in loads
      return _default_decoder.decode(s)
    File "/usr/lib/python2.7/json/decoder.py", line 366, in decode
      obj, end = self.raw_decode(s, idx=_w(s, 0).end())
    File "/usr/lib/python2.7/json/decoder.py", line 384, in raw_decode
      raise ValueError("No JSON object could be decoded")
  ValueError: No JSON object could be decoded

are not particularly clear.  With this commit, we'll get output like:

  $ ./nmbug-status
  fatal: Not a git repository: '/home/wking/.nmbug'
  No local branch 'config' in /home/wking/.nmbug.  Checkout a local
  config branch or explicitly set --config.

which is much more accessible.  I've also added user-friendly messages
for a number of other config-parsing errors.

lib: make notmuch_query_count_messages explicitely exact

The default is actually exact if no checkatleast parameter is
specified. This change makes that explicit, mainly for documentation,
but also to be safe in the unlikely event of a change of default.

[ commit message rewritten by db based on id:87lho0nlkk.fsf@nikula.org
]

completion: complete addresses in from:/to: search terms

Use the new notmuch address command to do completion for addresses in
from: and to:. Use --output=sender for both for efficiency, even
though --output=recipients would be more accurate for to: prefix
completion.

cli: add support for notmuch command --help

Recognize 'notmuch command --help' at the top level as a special case,
and show help for the command. Note that for simplicity, --help is
only recognized as the first option for the subcommand.

cli: fix top level --help combined with other options

If the top level --help is combined with other options, help
fails. For example:

    $ notmuch --version --help

    Sorry, --help is not a known command. There's not much I can do to help.

Fix this by adjusting argc and argv appropriately. The help command
ignores argv[0] anyway, so we don't have to set it to "help".