mu/man/mu-cfind.1

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

.SH NAME

\fBmu cfind\fR is the \fBmu\fR command to find contacts in the \fBmu\fR
database and export them for use in other programs.

.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)