#+title:  MU CFIND

* 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 Perl-compatible (as per the PCRE-library used by
GRegex).

* 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]        |


[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 2009-06-01, you could specify
# #+begin_example
#   --after=`date +%s --date='2009-06-01'`
# #+end_example

#+include: "muhome.inc" :minlevel 2

#+include: "common-options.inc" :minlevel 1

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

* EXIT CODE

This command returns 0 upon successful completion, or a non-zero exit code
otherwise: 1 for a generals error and 2 for 'no matches'.

#+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)*