mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-12-22 01:14:53 +01:00
contrib: new mutt-notmuch utility for Mutt integration
This commit is contained in:
Stefano Zacchiroli
David Bremner
parent
2b97293b15
commit
d13810dc1e
5 changed files with 320 additions and 0 deletions
2
contrib/notmuch-mutt/.gitignore
vendored
Normal file
2
contrib/notmuch-mutt/.gitignore
vendored
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
notmuch-mutt.1
|
||||
README.html
|
||||
12
contrib/notmuch-mutt/Makefile
Normal file
12
contrib/notmuch-mutt/Makefile
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
NAME = notmuch-mutt
|
||||
|
||||
all: $(NAME) $(NAME).1
|
||||
|
||||
$(NAME).1: $(NAME)
|
||||
pod2man $< > $@
|
||||
|
||||
README.html: README
|
||||
markdown $< > $@
|
||||
|
||||
clean:
|
||||
rm -f notmuch-mutt.1 README.html
|
||||
59
contrib/notmuch-mutt/README
Normal file
59
contrib/notmuch-mutt/README
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
notmuch-mutt: Notmuch (of a) helper for Mutt
|
||||
============================================
|
||||
|
||||
notmuch-mutt provide integration among the [Mutt] [1] mail user agent and the
|
||||
[Notmuch] [2] mail indexer.
|
||||
|
||||
notmuch-mutt offer two main integration features. The first one is the ability
|
||||
of stating a **search query interactively** and then jump to a fresh Maildir
|
||||
containing its search results only. The second one is the ability to
|
||||
**reconstruct threads on the fly** starting from the currently highlighted
|
||||
mail, which comes handy when a thread has been split across different maildirs,
|
||||
archived, or the like.
|
||||
|
||||
notmuch-mutt enables to trigger mail searches via a Mutt macro (usually F8) and
|
||||
reconstruct threads via another (usually F9). Check the manpage for the 2-liner
|
||||
configuration snippet for your Mutt configuration files (~/.muttrc,
|
||||
/etc/Muttrc, or a /etc/Muttrc.d snippet).
|
||||
|
||||
A [blog style introduction] [3] to notmuch-mutt is available and includes some
|
||||
more rationale for its existence.
|
||||
|
||||
Arguably, some of the logics of notmuch-mutt could disappear by adding support
|
||||
for a --output=symlinks flag to notmuch.
|
||||
|
||||
|
||||
[1]: http://www.mutt.org/
|
||||
[2]: http://notmuchmail.org/
|
||||
[3]: http://upsilon.cc/~zack/blog/posts/2011/01/how_to_use_Notmuch_with_Mutt/
|
||||
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
To *run* notmuch-mutt you will need Perl with the following libraries:
|
||||
|
||||
- Mail::Box <http://search.cpan.org/~markov/Mail-Box/>
|
||||
(Debian package: libmail-box-perl)
|
||||
- Mail::Internet <http://search.cpan.org/~markov/MailTools/>
|
||||
(Debian package: libmailtools-perl)
|
||||
- String::ShellQuote <http://search.cpan.org/~rosch/String-ShellQuote/ShellQuote.pm>
|
||||
(Debian package: libstring-shellquote-perl)
|
||||
- Term::ReadLine <http://search.cpan.org/~hayashi/Term-ReadLine-Gnu/>
|
||||
(Debian package: libterm-readline-gnu-perl)
|
||||
|
||||
To *build* notmuch-mutt documentation you will need:
|
||||
|
||||
- pod2man (coming with Perl) to generate the manpage
|
||||
- markdown to generate README.html out of this file
|
||||
|
||||
|
||||
License
|
||||
-------
|
||||
|
||||
notmuch-mutt is copyright (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>.
|
||||
|
||||
notmuch-mutt is released under the terms of the GNU General Public License
|
||||
(GPL), version 3 or above. A copy of the license is available online at
|
||||
<http://www.gnu.org/licenses/>.
|
||||
|
||||
238
contrib/notmuch-mutt/notmuch-mutt
Executable file
238
contrib/notmuch-mutt/notmuch-mutt
Executable file
|
|
@ -0,0 +1,238 @@
|
|||
#!/usr/bin/perl -w
|
||||
#
|
||||
# notmuch-mutt - notmuch (of a) helper for Mutt
|
||||
#
|
||||
# Copyright: © 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>
|
||||
# License: GNU General Public License (GPL), version 3 or above
|
||||
#
|
||||
# See the bottom of this file for more documentation.
|
||||
# A manpage can be obtained by running "pod2man notmuch-mutt > notmuch-mutt.1"
|
||||
|
||||
use strict;
|
||||
use warnings;
|
||||
|
||||
use File::Path;
|
||||
use Getopt::Long qw(:config no_getopt_compat);
|
||||
use Mail::Internet;
|
||||
use Mail::Box::Maildir;
|
||||
use Pod::Usage;
|
||||
use String::ShellQuote;
|
||||
use Term::ReadLine;
|
||||
|
||||
|
||||
my $xdg_cache_dir = "$ENV{HOME}/.cache";
|
||||
$xdg_cache_dir = $ENV{XDG_CACHE_HOME} if $ENV{XDG_CACHE_HOME};
|
||||
my $cache_dir = "$xdg_cache_dir/notmuch/mutt";
|
||||
|
||||
|
||||
# create an empty maildir (if missing) or empty an existing maildir"
|
||||
sub empty_maildir($) {
|
||||
my ($maildir) = (@_);
|
||||
rmtree($maildir) if (-d $maildir);
|
||||
my $folder = new Mail::Box::Maildir(folder => $maildir,
|
||||
create => 1);
|
||||
$folder->close();
|
||||
}
|
||||
|
||||
# search($maildir, $query)
|
||||
# search mails according to $query with notmuch; store results in $maildir
|
||||
sub search($$) {
|
||||
my ($maildir, $query) = @_;
|
||||
$query = shell_quote($query);
|
||||
|
||||
empty_maildir($maildir);
|
||||
system("notmuch search --output=files $query"
|
||||
. " | sed -e 's: :\\\\ :g'"
|
||||
. " | xargs --no-run-if-empty ln -s -t $maildir/cur/");
|
||||
}
|
||||
|
||||
sub prompt($$) {
|
||||
my ($text, $default) = @_;
|
||||
my $query = "";
|
||||
my $term = Term::ReadLine->new( "notmuch-mutt" );
|
||||
my $histfile = "$cache_dir/history";
|
||||
|
||||
$term->ornaments( 0 );
|
||||
$term->unbind_key( ord( "\t" ) );
|
||||
$term->MinLine( 3 );
|
||||
$histfile = $ENV{MUTT_NOTMUCH_HISTFILE} if $ENV{MUTT_NOTMUCH_HISTFILE};
|
||||
$term->ReadHistory($histfile) if (-r $histfile);
|
||||
while (1) {
|
||||
chomp($query = $term->readline($text, $default));
|
||||
if ($query eq "?") {
|
||||
system("man", "notmuch");
|
||||
} else {
|
||||
$term->WriteHistory($histfile);
|
||||
return $query;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
sub get_message_id() {
|
||||
my $mail = Mail::Internet->new(\*STDIN);
|
||||
$mail->head->get("message-id") =~ /^<(.*)>$/; # get message-id
|
||||
return $1;
|
||||
}
|
||||
|
||||
sub search_action($$@) {
|
||||
my ($interactive, $results_dir, @params) = @_;
|
||||
|
||||
if (! $interactive) {
|
||||
search($results_dir, join(' ', @params));
|
||||
} else {
|
||||
my $query = prompt("search ('?' for man): ", join(' ', @params));
|
||||
if ($query ne "") {
|
||||
search($results_dir,$query);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
sub thread_action(@) {
|
||||
my ($results_dir, @params) = @_;
|
||||
|
||||
my $mid = get_message_id();
|
||||
my $search_cmd = 'notmuch search --output=threads ' . shell_quote("id:$mid");
|
||||
my $tid = `$search_cmd`; # get thread id
|
||||
chomp($tid);
|
||||
|
||||
search($results_dir, $tid);
|
||||
}
|
||||
|
||||
sub tag_action(@) {
|
||||
my $mid = get_message_id();
|
||||
|
||||
system("notmuch tag "
|
||||
. shell_quote(join(' ', @_))
|
||||
. " id:$mid");
|
||||
}
|
||||
|
||||
sub die_usage() {
|
||||
my %podflags = ( "verbose" => 1,
|
||||
"exitval" => 2 );
|
||||
pod2usage(%podflags);
|
||||
}
|
||||
|
||||
sub main() {
|
||||
mkpath($cache_dir) unless (-d $cache_dir);
|
||||
|
||||
my $results_dir = "$cache_dir/results";
|
||||
my $interactive = 0;
|
||||
my $help_needed = 0;
|
||||
|
||||
my $getopt = GetOptions(
|
||||
"h|help" => \$help_needed,
|
||||
"o|output-dir=s" => \$results_dir,
|
||||
"p|prompt" => \$interactive);
|
||||
if (! $getopt || $#ARGV < 0) { die_usage() };
|
||||
my ($action, @params) = ($ARGV[0], @ARGV[1..$#ARGV]);
|
||||
|
||||
foreach my $param (@params) {
|
||||
$param =~ s/folder:=/folder:/g;
|
||||
}
|
||||
|
||||
if ($help_needed) {
|
||||
die_usage();
|
||||
} elsif ($action eq "search" && $#ARGV == 0 && ! $interactive) {
|
||||
print STDERR "Error: no search term provided\n\n";
|
||||
die_usage();
|
||||
} elsif ($action eq "search") {
|
||||
search_action($interactive, $results_dir, @params);
|
||||
} elsif ($action eq "thread") {
|
||||
thread_action($results_dir, @params);
|
||||
} elsif ($action eq "tag") {
|
||||
tag_action(@params);
|
||||
} else {
|
||||
die_usage();
|
||||
}
|
||||
}
|
||||
|
||||
main();
|
||||
|
||||
__END__
|
||||
|
||||
=head1 NAME
|
||||
|
||||
notmuch-mutt - notmuch (of a) helper for Mutt
|
||||
|
||||
=head1 SYNOPSIS
|
||||
|
||||
=over
|
||||
|
||||
=item B<notmuch-mutt> [I<OPTION>]... search [I<SEARCH-TERM>]...
|
||||
|
||||
=item B<notmuch-mutt> [I<OPTION>]... thread < I<MAIL>
|
||||
|
||||
=item B<notmuch-mutt> [I<OPTION>]... tag [I<TAGS>]... < I<MAIL>
|
||||
|
||||
=back
|
||||
|
||||
=head1 DESCRIPTION
|
||||
|
||||
notmuch-mutt is a frontend to the notmuch mail indexer capable of populating
|
||||
maildir with search results.
|
||||
|
||||
=head1 OPTIONS
|
||||
|
||||
=over 4
|
||||
|
||||
=item -o DIR
|
||||
|
||||
=item --output-dir DIR
|
||||
|
||||
Store search results as (symlink) messages under maildir DIR. Beware: DIR will
|
||||
be overwritten. (Default: F<~/.cache/notmuch/mutt/results/>)
|
||||
|
||||
=item -p
|
||||
|
||||
=item --prompt
|
||||
|
||||
Instead of using command line search terms, prompt the user for them (only for
|
||||
"search").
|
||||
|
||||
=item -h
|
||||
|
||||
=item --help
|
||||
|
||||
Show usage information and exit.
|
||||
|
||||
=back
|
||||
|
||||
=head1 INTEGRATION WITH MUTT
|
||||
|
||||
notmuch-mutt can be used to integrate notmuch with the Mutt mail user agent
|
||||
(unsurprisingly, given the name). To that end, you should define macros like
|
||||
the following in your Mutt configuration (usually one of: F<~/.muttrc>,
|
||||
F</etc/Muttrc>, or a configuration snippet under F</etc/Muttrc.d/>):
|
||||
|
||||
macro index <F8> \
|
||||
"<enter-command>unset wait_key<enter><shell-escape>notmuch-mutt --prompt search<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter>" \
|
||||
"notmuch: search mail"
|
||||
macro index <F9> \
|
||||
"<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt thread<enter><change-folder-readonly>~/.cache/notmuch/mutt/results<enter><enter-command>set wait_key<enter>" \
|
||||
"notmuch: reconstruct thread"
|
||||
macro index <F6> \
|
||||
"<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt tag -inbox<enter>" \
|
||||
"notmuch: remove message from inbox"
|
||||
|
||||
The first macro (activated by <F8>) prompts the user for notmuch search terms
|
||||
and then jump to a temporary maildir showing search results. The second macro
|
||||
(activated by <F9>) reconstructs the thread corresponding to the current mail
|
||||
and show it as search results. The third macro (activated by <F6>) removes the
|
||||
tag C<inbox> from the current message; by changing C<-inbox> this macro may be
|
||||
customised to add or remove tags appropriate to the users notmuch work-flow.
|
||||
|
||||
To keep notmuch index current you should then periodically run C<notmuch
|
||||
new>. Depending on your local mail setup, you might want to do that via cron,
|
||||
as a hook triggered by mail retrieval, etc.
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
mutt(1), notmuch(1)
|
||||
|
||||
=head1 AUTHOR
|
||||
|
||||
Copyright: (C) 2011-2012 Stefano Zacchiroli <zack@upsilon.cc>
|
||||
|
||||
License: GNU General Public License (GPL), version 3 or higher
|
||||
|
||||
=cut
|
||||
9
contrib/notmuch-mutt/notmuch-mutt.rc
Normal file
9
contrib/notmuch-mutt/notmuch-mutt.rc
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
macro index <F8> \
|
||||
"<enter-command>unset wait_key<enter><shell-escape>notmuch-mutt --prompt search<enter><change-folder-readonly>`echo ${XDG_CACHE_HOME:-$HOME/.cache}/notmuch/mutt/results`<enter>" \
|
||||
"notmuch: search mail"
|
||||
macro index <F9> \
|
||||
"<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt thread<enter><change-folder-readonly>`echo ${XDG_CACHE_HOME:-$HOME/.cache}/notmuch/mutt/results`<enter><enter-command>set wait_key<enter>" \
|
||||
"notmuch: reconstruct thread"
|
||||
macro index <F6> \
|
||||
"<enter-command>unset wait_key<enter><pipe-message>notmuch-mutt tag -inbox<enter>" \
|
||||
"notmuch: remove message from inbox"
|
||||
Loading…
Reference in a new issue