Man1 - mu-cfind.1

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

mu cfind [options] [<pattern>]

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.

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:

     $ mu cfind '@gmail.com'

would find all contacts with a gmail-address, while

     $ mu cfind Mary

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

*–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 (*)	  |

() 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 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 in mu index.
• –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

    --after=`date +%s --date='2009-06-01'`

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

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

You can use mu cfind as an external address book server for mutt. For this to work, add the following to your muttrc:

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

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

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.

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

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

mu*(1), *mu-index*(1), *mu-find*(1), *pcrepattern(3)