changelog for 0.37~rc0-3

debian: changelog for 0.37~rc0-2

debian: upload release candidate to experimental, not unstable

Oops, tagged "upstream" version is incorrect, but it's a minor issue.

debian: changelog stanza for 0.37~rc0-1

version: update to 0.37~rc0

doc/emacs: use define-key instead of hard-coding markup

Add keys to index. Allow indexing of both keys and commands. Use
standard typesetting for multiple keybindings.

doc/emacs: replace use of emacsvar with el:defcustom

Mainly this allows dropping the ad-hoc directive emacsvar

doc/emacs: replace emacscmd with el:define-key

This allows us to eliminate the ad-hoc emacscmd directive / role, and
improve indexing.

doc/emacs: convert remaining uses of emacscmd to define-key

This allows us to remove the no-longer used object type.

doc/emacs: split index category from label

A more verbose category is needed for the index, but not the
description in the manual.

doc/emacs: drop domain label

This makes the generate info files somewhat less verbose, so that they
say e.g. "Key Binding" instead of "Emacs Key Binding"

doc/elisp: replace label for Emacs commands and key bindings.

In the notmuch doc index it is important to be clear which parts are
Emacs related.

doc: copy elisp.py from flycheck, make available

This corresponds to flycheck commit
1702d2db3d8ba9bcb9b2bf810e791e907fcc3adc, which is apparently the last
time this file was modified (2018).

Embedding seems defensible since the file is evidently not changing
that much, and we need to change some labels to make it fit with the
not-just-emacs nature of notmuch docs.

doc: add some documentation about duplicate files.

This is mainly motivated by the new emacs-UI features to select
duplicates, but hopefully it will help demystify things for users of
the CLI as well.

emacs: add docstring for notmuch-show-choose-duplicate

It should have one in any case, but in particular it is needed for the
manual.

emacs/show: restrict inlined mimetypes on refresh.

This fixes the bug reported by Al [1]. Essentially apply the same fix
as [2] in a different place.

[1]: id:877d41nmr1.fsf@gmail.com
[2]: 90a7c1af368a527700dcde9b0dcbd760afc7bd92

test/emacs: add known broken test for inlining on refresh.

This duplicates the bug reported by Al [1]

[1]: id:877d41nmr1.fsf@gmail.com

emacs: add duplicate support to notmuch-show-view-raw-message

This fixes one of the bugs reported by Gregor in [1]

[1]: id:87edxw8jp4.fsf@no.workgroup

emacs/show: provide a more friendly function to get duplicate num

There is not much code here, but at least we can fix the indexing as 1
based.

test/emacs: add known broken test for viewing raw duplicate

This duplicates one of the bugs reported by Gregor in [1].

[1]: id:87edxw8jp4.fsf@no.workgroup

emacs: update notmuch-show-get-filename to handle duplicates

This fixes one of the bugs reported by Gregor in [1].

[1]: id:87edxw8jp4.fsf@no.workgroup

test/emacs: add known broken test for stashing duplicate filename

This duplicates (no pun intended) one of the bugs reported by Gregor
in id:87edxw8jp4.fsf@no.workgroup

NEWS: initial set of NEWS for 0.37.

There are one or two more changes to apply (and potentially document)
before release, but this covers most of my commits.

doc/notmuch: merge two sections on external commands.

When adding the description of the propagation of NOTMUCH_CONFIG, I
missed that there was already a section on external commands, with a
different title.

tests: remove dead code from T055-path-config.sh

This case statement does nothing.

notmuch.c: add missing trailing newlines in two error messages

Removed duplicate error check (and the message) in 3rd case where
the same error message (w/o trailing newline) was present.

In case of test/T040-setup.sh, command substitution deletes
trailing newlines, so related test there cannot be changed
(and therefore could not notice this user experience flaw).

doc/emacs: add docstring for notmuch-unthreaded-result-format.

The main change is actually updating cross references.

emacs: update defcustom for notmuch-unthreaded-result-format

This is essentially a copy of that for notmuch-tree-result-format,
aside from the default value.

doc/emacs: add docstring and example for n-tree-result-format

This example is based on one originally by Jon Hurst.

emacs: update defcustom for notmuch-search-result-format.

It seems redundant to have the previous example, since the default
value is always show by describe variable.

Enforce more restrictions on the keys in the alist, since arbitrary
strings don't work as field names.

Document that functions can be used in lieu of field names.

doc/emacs: add docstring and example for n-search-result-format

When the ability to use functions was added, this example was confined
to a commit message, which is not user discoverable.

emacs: update defcustom for notmuch-search-result-format.

It seems redundant to have the previous example, since the default
value is always show by describe variable.

Enforce more restrictions on the keys in the alist, since arbitrary
strings don't work as field names.

Document that functions can be used in lieu of field names.

emacs/reply: reply to correct duplicate

Essentially we just need to arrange to pass the right --duplicate
argument to notmuch reply.

As a side-effect, correct the previously unused value of EXPECTED in
T453-emacs-reply.sh.

CLI/reply: support --duplicate argument

We want the reply used to match that shown e.g. in the emacs
interface. As a first step provide that functionality on the command
line.

Schema does not need updating as the duplicate key was already
present (with a constant value of 1).

emacs/show: display count of duplicates in headerline

There is no real cost here, except screen real estate. Some people
might prefer hiding the duplicate count, but we leave that for a
future commit.

emacs/show: provide notmuch-show-choose-duplicate

This new command allows the user to interactively choose a different
duplicate (file) to display for a given message in
notmuch-show-mode. Since both tree and unthreaded view use
notmuch-show-mode, this provides the same facility there.

CLI/show: support --duplicate for structured output

This introduces a new mandatory key for message structures, namely
"duplicate". Per convention in devel/schemata this does _not_ increase
the format version. This means that clients are responsible for
checking that it exists, and not crashing if it does not.

The main functional change is teaching mime_node_open to understand a
'duplicate' argument.

Support for --duplicate in notmuch-reply would make sense, but we
defer it to a later commit.

CLI/show: initial support for --duplicate for (raw output only)

Add command line argument --duplicate, analogous with that already
supported for notmuch-search.

Use of a seperate function for _get_filename is mainly a form of
documentation at this point.

md5sum is of course a weak hash, but it is good enough for
this (non-adversarial) test suite use.

CLI/git: opportunistically use bindings to check for known messages

If the bindings are installed, use them to avoid one exec of notmuch
search per message.

CLI/git: current cache contents of index

Rather than shelling out once per message to get the list of files
corresponding to tags, it is much faster (although potentially a bit
memory intensive) to read them all at once.

perf-test: add tests notmuch-git

The main focus of these initial tests is the (currently unacceptably
slow) checkout performance.

doc/emacs: add notmuch-show-empty-saved-searches to manual

Answering a user question, I had to dig for this variable, but I think
it is a reasonably common customization wish, particularly for users
with custom count-functions.

doc/emacs: define and use emacsvar and emacscmd markup

This makes it easier to navigate the merged index of all of the
notmuch documentation.

doc: do not generate python module index

This currently seems unhelpful, and not generating it removes if from
the navigation bar, which prevents mis-clicking.

doc: drop module index from ToC

There is only one module listed, so the index is not useful.

doc: retitle notmuch-emacs manual

This makes the HTML TOC read more naturally. Add a label to make cross
referencing easier.

doc: reorganize sphinx toctree

This mainly affects the html output (although users generating epub or
pdf would also notice a change). The goal is twofold: make the TOC a
bit friendler and easier to navigate by introducing some hierarchy,
and allow links for nmbug and notmuch-setup.

doc: improve config item labels in info output

Commit 306b7028d added the nmconfig role / directive. Unfortunately
the default of using the directive name in texinfo output is pretty
ugly, so attempt to make it more human readable by passing `objname`
to add_object_type invocation.

doc/emacs: add discussion about notmuch-show performance.

Most of the information is already in the docstrings, but hopefully
by grouping it is more discoverable.

emacs/show: introduce notmuch-show-height-limit

Analogous to notmuch-show-depth-limit, it requires a bit more
calculation, but that cost seems dominated by the rendering cost.

emacs/show: obey notmuch-show-max-text-part-size for part 0

This parameter was originally introduced to hide large attachements
that happened to be text/plain. From a performance point of view,
there is no reason not to also hide large message bodies.

emacs/show: optionally insert bodies of "deep messages" lazily

This leverages the machinery already there to insert buttons for
attachments.

A potential use-case is browsing the top layers of the tree to decide
which of the lower subtrees to read.

perf-test/emacs: test showing longish threads

This particular thread takes about 100 times longer to display in
emacs than on the command line.

The parameter notmuch-show-max-text-part-size exists, but is currently
ineffective for this task because it only hides attachments, not
part 0.

In future commits, the parameter notmuch-show-{depth,height}-limit
will trigger a similar kind of hiding for bodies as
n-s-m-text-part-size already does for attachments.

debian: add git as a build-dependency, for the test suite

This is needed to run (and test) notmuch-git.

CLI/git: add --format-version argument to init subcommand

This is primarily intended to support testing upward compatibility
with legacy repos.

CL/git: add format version 1

The original nmbug format (now called version 0) creates 1
subdirectory of 'tags/' per message. This causes problems for more
than (roughly) 100k messages.

Version 1 introduces 2 layers of hashed directories. This scheme was
chose to balance the number of subdirectories with the number of extra
directories (and git objects) created via hashing.

This should be upward compatible in the sense that old repositories
will continue to work with the updated notmuch-git.

CLI/git: replace most mentions of nmbug

Particularly in help messages, nmbug is confusing for users who may
have never heard of it.

test: known broken test for top level .notmuch in split configs

In split configurations there is no special significance to a top
level directory called .notmuch in the mail root. Users should
therefore be able to have mail stored underneath it.

bindings/python-cffi: fix docstring

the method Database.get_message does exist any more (if it ever
did). This makes the docstring unhelpful as an example.

test: add new corpus of duplicate messages

This corpus will be used to test a new --duplicate option for notmuch-show

test: define and use notmuch_sexp_*_sanitize functions

These are based on the equivalent functions for json. Like those,
these are pretty simple-minded, and don't really understand the
syntax.

test: use notmuch_json_show_sanitize more places

This makes the tests more robust against changing output formats, by
allowing us to centralize fixes in the sanitization function. It is
not appropriate for all cases, in particular it is unneeded when using
test_json_nodes, and unhelpful when testing filenames.

doc: replace symlink with copies for nmbug, notmuch-setup

Previously only man page aliases were being added as symlinks.  The
addition to man_pages in conf.py automatically propagates to the list
of generated info pages.

Installation of the new pages is handled by existing recipes.

emacs: mark notmuch-query.el as obsolete

The only functionality actually used by notmuch is the base function
notmuch-query-get-threads; the other functions in this file have
nothing to do with that (single) use.  Move that function into
notmuch-lib.el and rename to reflect use. Deprecate the other
functions in notmuch-query.el.

lib/sexp: add parameter expansion for regex and wildcard

Fix the bug reported at [1].

The parameter expansion for regex and wildcard modifiers has to be
done a bit differently, because their arguments are not s-expressions
defining complete Xapian queries.

[1]: id:87o7yxqxy6.fsf@code.pm

test/sexp: add known broken tests for macro param inside rx/wildcard

These tests replicate the problem reported by Eric Colson [1] (for the
regex case).

[1]: id:87o7yxqxy6.fsf@code.pm

make git ignore new build products

nmbug and notmuch-git are new build products. Make git ignore them just
like other build products.

Signed-off-by: Michael J Gruber <git@grubix.eu>

doc/sexp: document range queries.

Give examples for date fields, as these are commonly useful for user
queries.

lib/sexp: allow * as alias for "" in range searches.

It can be tedious to use "" inside of a string, e.g. in a shell script.

lib/sexp: special case "" as an argument in lastmod ranges.

Support this syntax for constincy with (data from to) ranges.

test/sexp: one sided range searches.

The date range parsing machinery already knows how to do something
appropriate with an empty string, but the lastmod parsing blindly
tries to parse each atom as a number.

lib: check for writable db in n_m_tags_maildir_flags

The database needs to be writable because the list of stored file
names will change in general.

lib: add NOTMUCH_STATUS_CLOSED_DATABASE, use in _n_d_ensure_writable

In order for a database to actually be writeable, it must be the case that it
is open, not just the correct type of Xapian object. By explicitely
checking, we are able to provide better error reporting, in particular
for the previously broken test in T566-lib-message.

lib: Add missing private status values.

These were missed when the corresponding status codes were added.

lib/tag: handle NULL argument to notmuch_tags_valid

Make the behaviour when passed NULL consistent with
notmuch_filenames_valid. The library already passes the result of
notmuch_message_get_tags without checking for NULL, so it should be
handled.

test: add known broken test for notmuch_tags_valid (NULL)

This should return false, but currently segfaults.

Start a new file for tags library API related tests. This is maybe
overkill, but new C boilerplate which doesn't corrupt the database is
needed anyway.

test: error handling for n_m_tags_to_maildir_flags

The closed database case should fail gracefully, but currently it
segfaults.

test: error handling in _n_message_{add,remove}_filename

Use a closed database to force throwing a Xapian exception. Leave the
check vague to accomodate a potential explicit check for open database.

lib/message: check return status from _n_m_add_{path,folder}_terms

Mainly to propagate information about Xapian exceptions.

lib/message: check return status of _n_m_{add,remove}_term

Xapian exceptions are not something that can be ignored, in general.

lib: define macro NODISCARD

In either C++17 (or later) mode, or when running cppcheck, this can be
used to selectively generate warnings about discarded return values.

lib/message: drop _notmuch_message_get_thread_id_only

This function has been unused since commit 4083fd8.

test: _notmuch_message_remove_term catches exceptions.

Unfortunately we can't differentiate between the two distinct error
conditions for Document::remove_term.

lib/message: catch exceptions in _n_m_add_term

Some code movement is needed to make sure the cache is only
invalidated when the Xapian operation succeeds.

test: define test_private_C

When testing error handling, it is sometimes difficult to cover a
particular error path deterministically. Introduce a test function to
allow calling lower level functions directly.

CLI: set NOTMUCH_CONFIG in hooks.

This addresses a bug report / feature request of Uwe Kleine-König. The
assumption is that we always load a config file in the CLI (i.e. we
never pass "" as the config file argument to
notmuch_database_open_with_config).

[1]: id:8baa58c3-7ab9-ec03-1bbd-28aa5be838f2@kleine-koenig.org

test: add known broken tests for setting NOTMUCH_CONFIG in hooks

Setting this according to --config was requested by Uwe
Kleine-König. There are some other ways that the configuration file
might be found in current notmuch, so check those as well.

As a bonus, fix a bug in the hook tests that left NOTMUCH_CONFIG set
even though a config file was provided via NOTMUCH_PROFILE.

[1]: id:8baa58c3-7ab9-ec03-1bbd-28aa5be838f2@kleine-koenig.org

debian: install notmuch-git

Use a separate binary package to avoid dragging in dependencies on
python and git for those that do not want them.

CLI/git: add safety checks for checkout and commit

Commits or checkouts that modify a large fraction of the messages in
the database should be relatively rare (and in some automated process,
probably non-existent). For initial setup, where such operations are
expected, the user can pass --force.

CLI/git: support configuration for repo location / prefix

This is probably more convenient than always passing a command line
argument.

Use notmuch-config for consistency with other notmuch CLI tools.

Now that there is something relevant in the config files, test the
--config option.

CLI/git: change defaults for repo and prefix

The previous defaults were not suitable for personal (i.e. not
bugtracking for notmuch development) use.

Provide two ways for the user to select nmbug compatible defaults;
command line argument and checking the name of the script.

doc/notmuch-git: initial documentation

This is mainly derived from the various help outputs from the script,
with some massaging of markup and addition of links.

CLI/git: cache git indices

If the private index file matches a previously known revision of the
database, we can update the index incrementally using the recorded
lastmod counter. This is typically much faster than a full update,
although it could be slower in the case of large changes to the
database.

The "git-read-tree HEAD" is also a bottleneck, but unfortunately
sometimes is needed. Cache the index checksum and hash to reduce the
number of times the operation is run. The overall design is a
simplified version of the PrivateIndex class.

CLI/git: add @timed decorator, time a few functions

Perf will show which binaries are using the CPU cycles, and standard
python profilers will show which python functions, but neither is
great at finding which call to an external binary is taking time, or
locating I/O hotspots.

CLI/git: replace enumeration of tags with sexp query.

Unlike the (current) infix query parser provided by Xapian, the
notmuch specific sexp query parser supports prefixed wildcard queries,
so use those. In addition to being somewhat faster, this avoids
needing to escape all of the user's tags to pass via the shell.

test/git: add known broken test for tag with quotes.

There is current insufficient sanitization and/or escaping of tag names
internally in notmuch-git.

CLI/git: suppress warnings about initial branch name

The canonical nmbug repository still uses "master" as the main branch
name, so defer any potential switch away from that name.

CLI/git: rename environment variables.

Although the code required to support both new and old environment
variables is small, it complicates the semantics of configuration, and
make the documentation harder to follow.

test: initial tests for notmuch-git

Exercise the main functionality of notmuch-git.  add_git_repos() will
hopefully be simplifed when an init subcommand is added.

CLI/git: Add an 'init' command

For folks that want to start versioning a new tag-space, instead of
cloning one that someone else has already started.

The empty-blob hash-object call avoids errors like:

  $ nmbug commit
  error: invalid object 100644 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 for
'tags/...'
  fatal: git-write-tree: error building trees
  'git HASH(0x9ef3eb8) write-tree' exited with nonzero value

David Bremner suggested [1]:

  $ git hash-object -w /dev/null

instead of my Python version of:

  $ git hash-object -w --stdin <&-

but I expect that closing stdin is more portable than the /dev/null
path (which doesn't exist on Windows, for example).

The --bare init and use of NMBGIT as the work tree (what could go
wrong with an empty commit?) are suggestions from Michal Sojka [2].

[1]: id:87y4vu6uvf.fsf@maritornes.cs.unb.ca
     http://thread.gmane.org/gmane.mail.notmuch.general/18626/focus=18720
[2]: id:87a93a5or2.fsf@resox.2x.cz
     http://thread.gmane.org/gmane.mail.notmuch.general/19495/focus=19767

CLI/git: make existance of config branch optional on clone

This branch is actually only used by an associated
utility (notmuch-report), and notmuch-git works fine without it.