1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
#+TITLE: MU CFIND
#+MAN_CLASS_OPTIONS: :section-id "@SECTION_ID@" :date "@MAN_DATE@"
#+include: macros.inc
* 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). Different output formats
are available, e.g., 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. If the same
e-mail address is used with different names, the most recent non-empty name is
used. If that is not the desired name, see *CORRECTING* below.
*mu cfind* starts a search for contacts that match a =regular expression=. For
example:
#+begin_example
$ mu cfind '@gmail\.com'
#+end_example
finds 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. *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 {{{man-link(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:
#+ATTR_MAN: :disable-caption t
| --format= | description |
|-------------+-----------------------------------|
| plain | default, simple list |
| mutt-alias | mutt alias-format |
| mutt-ab | mutt external address book format |
| wl | wanderlust address book 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.
** -p, --personal
Only show addresses seen in messages where at least one of personal e-mail
addresses was seen in any of the address fields; this is to exclude addresses
only seen in mailing-list messages. See the *--personal-address* parameter to *mu
init* for specifying your personal e-mail addresses.
** --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:
#+ATTR_MAN: :disable-caption t
| 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 {{{man-link(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.
* CORRECTING
If you want to correct the name for a given contact, one trick is to manual
create an e-mail message with some future date that has all the correct name /
e-mail address combinations, and put this in the Maildir you use.
#+include: "exit-code.inc" :minlevel 1
#+include: "bugs.inc" :minlevel 1
#+include: "author.inc" :minlevel 1
#+include: "copyright.inc" :minlevel 1
* SEE ALSO
{{{man-link(mu,1)}}},
{{{man-link(mu-index,1)}}},
{{{man-link(mu-find,1)}}},
{{{man-link(pcre,3)}}},
{{{man-link(jq,1)}}}
|
