#contact #address-book #vcard #vdir

bin+lib mates

A very simple commandline addressbook

6 releases

Uses old Rust 2015

0.3.0 Dec 31, 2017
0.2.0 May 11, 2017
0.1.4 Mar 25, 2016
0.1.2 Feb 20, 2016
0.1.1 Dec 16, 2015

#148 in Email

24 downloads per month

MIT license

31KB
687 lines

Mates

Build status

A commandline addressbook. The main goals are:

  • High extensibility

    • Mates operates on a directory of vCard files, a standardized file format for contacts. Because of this, another program can be used for synchronization with CardDAV-servers (see below).
  • UI responsiveness For completing email addresses in mutt, mates maintains a simple textfile with only a few fields from the vCard file, on which it calls grep. The textfile looks like this:

    work@example.com\tExample Man\t/home/user/.contacts/exampleman.vcf
    home@example.com\tExample Man\t/home/user/.contacts/exampleman.vcf
    

Installation

On ArchLinux, simply use the mates-git package from the AUR.

For a manual installation, you need to have Rust and Cargo installed. Both 1.0 and the nightlies should work.

  1. cargo install mates (or cargo install --git https://github.com/untitaker/mates.rs to install the dev version)
  2. Add ~/.cargo/bin/ to your path. The binary inside it doesn't depend on either Rust or Cargo, just glibc and grep.

Shell completions

Shell completion files are included in the ArchLinux package for Bash, Fish, and Zsh. cargo install currently does not support installing additional files.

If building from source, they will be found in target/release/build/mates-<hash>/out/<shellfile>.

Usage

Set the environment variable MATES_DIR to your directory of .vcf-files. Then run the binary with --help to list all commands.

The other environment variables are:

  • MATES_GREP, override the grep binary to use. Default to grep. This command must accept a search string as first argument and a filepath as second one.
  • MATES_INDEX, the filepath to the contact index. Default to ~/.mates_index.

Note: "mates index" must be called regularly. Even when using mates' own commands, the index will not be updated automatically, as this would impact UI responsiveness massively.

Integration

Mutt

Query command in mutt (email autocompletion)

# ~/.muttrc

set query_command= "mates mutt-query '%s'"

# Normally you'd have to hit Ctrl-T for completion.
# This rebinds it to Tab.
bind editor <Tab> complete-query
bind editor ^T    complete

Create new contact from message

# ~/.muttrc

macro index,pager A \
    "<pipe-message>mates add | xargs mates edit<enter>" \
    "add the sender address"

With this configuration, hitting A when viewing a message or highlighting it in the folder view will add it to your contacts and open the new contact in your editor. If you clear the file, the new contact will be deleted.

Using fuzzy finders for email selection

selecta and fzf are tools that can be used instead of grep to search for contacts:

m() {
    mutt "$(MATES_GREP=selecta mates email-query)"
}

m() {
    mutt "$(MATES_GREP='fzf -q' mates email-query)"
}

Selecta is much more lightweight than fzf, but fzf provides a nicer interface on the other hand.

Synchronization with CardDAV (Vdirsyncer)

Vdirsyncer can be used to synchronize mates' MATES_DIR with CardDAV-servers. Here is a simple example configuration, where MATES_DIR=~/.contacts/:

[pair contacts]
a = contacts_local
b = contacts_remote

[storage contacts_local]
type = filesystem
path = ~/.contacts/
fileext = .vcf

[storage contacts_remote]
type = carddav
url = https://davserver.example.com/
username = foouser
password = foopass

License

Mates is released under the MIT license, see LICENSE for details.

Dependencies

~11MB
~182K SLoC