mirror of
https://github.com/djcb/mu.git
synced 2024-06-27 07:35:16 +02:00
0ab2371c5c
It was still there, but disabled. Fixes #2470.
160 lines
5.5 KiB
Org Mode
160 lines
5.5 KiB
Org Mode
#+TITLE: MU CFIND
|
|
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
|
|
|
|
* NAME
|
|
*mu cfind* is the *mu* command to 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:
|
|
|
|
#+begin_example
|
|
$ mu cfind '@gmail\.com'
|
|
#+end_example
|
|
|
|
would find all contacts with a gmail-address, while
|
|
|
|
#+begin_example
|
|
$ mu cfind Mary
|
|
#+end_example
|
|
|
|
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
|
|
#+begin_example
|
|
--after=`date +%s --date='2020-06-01'`
|
|
#+end_example
|
|
|
|
#+include: "muhome.inc" :minlevel 2
|
|
|
|
#+include: "common-options.inc" :minlevel 1
|
|
|
|
* JSON FORMAT
|
|
|
|
With ~--format=json~, the matching contacts come out as a JSON array, e.g.,
|
|
#+begin_example
|
|
[
|
|
{
|
|
"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
|
|
}
|
|
]
|
|
#+end_example
|
|
|
|
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:
|
|
#+begin_example
|
|
$ mu cfind --format=json --personal | jq -r '.[] | ."last-seen-iso" + " " + .display' | sort
|
|
#+end_example
|
|
|
|
* 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=:
|
|
|
|
#+begin_example
|
|
set query_command = "mu cfind --format=mutt-ab '%s'"
|
|
#+end_example
|
|
|
|
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.
|
|
|
|
#+include: "exit-code.inc" :minlevel 1
|
|
|
|
#+include: "bugs.inc" :minlevel 1
|
|
|
|
#+include: "author.inc" :minlevel 1
|
|
|
|
#+include: "copyright.inc" :minlevel 1
|
|
|
|
* SEE ALSO
|
|
*mu(1)*, *mu-index(1)*, *mu-find(1)*, *pcre(3)*, *jq(1)*
|