c76aa53156
The command names are formatted inconsistently, e.g.:
* NAME
~mu add~ - add one or more messages to the database
versus:
* NAME
*mu cfind* is the *mu* command to find contacts in the *mu* database and export them
versus:
* NAME
mu server - the mu backend for the mu4e e-mail client
and the format, with a space between "mu" and the subcommand, is not compatible
with mandb(8). Use formatting which is consistent and replace the spaces with
hyphens.
Signed-off-by: Jeremy Sowden <azazel@debian.org>
5.6 KiB
MU CFIND
- NAME
- SYNOPSIS
- DESCRIPTION
- SEARCHING CONTACTS
- CFIND OPTIONS
- JSON FORMAT
- INTEGRATION WITH MUTT
- ENCODING
- SEE ALSO
NAME
mu-cfind - find contacts in the mu database and export them for use in other programs.
SYNOPSIS
mu [common-options] cfind [options] [<pattern>]
DESCRIPTION
mu cfind is the mu command for finding contacts (name and e-mail address of
people who were either an e-mail's sender or receiver). There are different
output formats available, for importing the contacts into other programs.
SEARCHING CONTACTS
When you index your messages (see mu index), mu creates a list of unique e-mail addresses found and the accompanying name, and caches this list. In case the same e-mail address is used with different names, the most recent non-empty name is used.
mu cfind starts a search for contacts that match a regular expression. For
example:
$ mu cfind '@gmail\.com'
would find all contacts with a gmail-address, while
$ mu cfind Mary
lists all contacts with Mary in either name or e-mail address.
If you do not specify a search expression, mu cfind returns the full list of contacts. Note, mu cfind uses a cache with the e-mail information, which is populated during the indexing process.
The regular expressions are basic case-insensitive PCRE, see pcre(3).
CFIND OPTIONS
–format=plain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv
sets the output format to the given value. The following are available:
| –format= | description |
|---|---|
| plain | default, simple list |
| mutt-alias | mutt alias-format |
| mutt-ab | mutt external address book format |
| wl | wanderlust addressbook format |
| org-contact | org-mode org-contact format |
| bbdb | BBDB format |
| csv | comma-separated values [1] |
| json | JSON format |
[1] CSV is not fully standardized, but mu cfind follows some common practices: any double-quote is replaced by a double-double quote (thus, "hello" become ""hello"", and fields with commas are put in double-quotes. Normally, this should only apply to name fields.
–personal,-p only show addresses seen in messages where one of 'my' e-mail
addresses was seen in one of the address fields; this is to exclude addresses
only seen in mailing-list messages. See the --my-address parameter to mu init.
–after=<timestamp> only show addresses last seen after
<timestamp>. <timestamp> is a UNIX time_t value, the number of
seconds since 1970-01-01 (in UTC).
From the command line, you can use the date command to get this value. For example, only consider addresses last seen after 2020-06-01, you could specify
--after=`date +%s --date='2020-06-01'`
JSON FORMAT
With --format=json, the matching contacts come out as a JSON array, e.g.,
[
{
"email" : "syb@example.com",
"name" : "Sybil Gerard",
"display" : "Sybil Gerard <syb@example.com>",
"last-seen" : 1075982687,
"last-seen-iso" : "2004-02-05T14:04:47Z",
"personal" : false,
"frequency" : 14
},
{
"email" : "ed@example.com",
"name" : "Mallory, Edward",
"display" : "\"Mallory, Edward\" <ed@example.com>",
"last-seen" : 1425991805,
"last-seen-iso" : "2015-03-10T14:50:05Z",
"personal" : true,
"frequency" : 2
}
]
Each contact has the following fields:
| property | description |
|---|---|
email |
the email-address |
name |
the name (or none) |
display |
the combination name and e-mail address for display purposes |
last-seen |
date of most recent message with this contact (Unix time) |
last-seen-iso |
last-seen represented as an ISO-8601 timestamp |
personal |
whether the email was seen in a message together with a personal address |
frequency |
approximation of the number of times this contact was seen in messages |
The JSON format is useful for further processing, e.g. using the jq(1) tool:
List display names, sorted by their last-seen date:
$ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort
INTEGRATION WITH MUTT
You can use mu cfind as an external address book server for mutt.
For this to work, add the following to your muttrc:
set query_command = "mu cfind --format=mutt-ab '%s'"
Now, in mutt, you can search for e-mail addresses using the query-command, which is (by default) accessible by pressing Q.
ENCODING
mu cfind output is encoded according to the current locale except for
--format=bbdb. This is hard-coded to UTF-8, and as such specified in the
output-file, so emacs/bbdb can handle things correctly, without guessing.
SEE ALSO
mu(1), mu-index(1), mu-find(1), pcre(3), jq(1)