.TH MU-CFIND 1 "April 2019" "User Manuals"

.SH NAME

mu_cfind \- find and export contacts in the \fBmu\fR database

.SH SYNOPSIS

.B mu cfind [options] [<pattern>]

.SH DESCRIPTION

\fBmu cfind\fR is the \fBmu\fR command for finding \fIcontacts\fR (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.

.SH SEARCHING CONTACTS

When you index your messages (see \fBmu index\fR), \fBmu\fR 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.

\fBmu cfind\fR starts a search for contacts that match a \fIregular
expression\fR. For example:

.nf
   $ mu cfind '@gmail\.com'
.fi

would find all contacts with a gmail-address, while

.nf
   $ mu cfind Mary
.fi

lists all contacts with Mary in either name or e-mail address.

If you do not specify a search expression, \fBmu cfind\fR returns the full list
of contacts. Note, \fBmu cfind\fR uses a cache with the e-mail information,
which is populated during the indexing process.

The regular expressions are Perl-compatible (as per the PCRE-library used by
GRegex).

.SH OPTIONS

.TP
\fB\-\-format\fR=\fIplain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv\fR
sets the output format to the given value. The following are available:

.nf
| --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 (*)	  |
.fi


(*) CSV is not fully standardized, but \fBmu cfind\fR 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.

.TP
\fB\-\-personal\fR 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 \fB\-\-my-address\fR parameter in
\fBmu index\fR.

.TP
\fB\-\-after=\fR\fI<timestamp>\fR only show addresses last seen after
\fI<timestamp>\fR. \fI<timestamp>\fR is a UNIX \fBtime_t\fR value, the number of
seconds since 1970-01-01 (in UTC).

From the command line, you can use the \fBdate\fR command to get this value. For
example, only consider addresses last seen after 2009-06-01, you could specify
.nf
  --after=`date +%s --date='2009-06-01'`
.fi

.SH RETURN VALUE

\fBmu cfind\fR returns 0 upon successful completion -- that is, at least one
contact was found. Anything else leads to a non-zero return value:

.nf
| code | meaning                        |
|------+--------------------------------|
|    0 | ok                             |
|    1 | general error                  |
|    2 | no matches (for 'mu cfind')    |
.fi

.SH INTEGRATION WITH MUTT

You can use \fBmu cfind\fR as an external address book server for \fBmutt\fR.
For this to work, add the following to your \fImuttrc\fR:

.nf
set query_command = "mu cfind --format=mutt-ab '%s'"
.fi

Now, in mutt, you can search for e-mail addresses using the \fBquery\fR-command,
which is (by default) accessible by pressing \fBQ\fR.

.SH ENCODING

\fBmu cfind\fR output is encoded according to the current locale except for
\fI--format=bbdb\fR. This is hard-coded to UTF-8, and as such specified in the
output-file, so emacs/bbdb can handle things correctly, without guessing.

.SH BUGS

Please report bugs if you find them at \fBhttps://github.com/djcb/mu/issues\fR.

.SH AUTHOR

Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

.SH "SEE ALSO"

.BR mu (1),
.BR mu-index (1),
.BR mu-find (1),
.BR pcrepattern(3)