https://github.com/pimutils/mates.rs

Very simple commandline addressbook
https://github.com/pimutils/mates.rs

Last synced: about 1 year ago
JSON representation

Very simple commandline addressbook

• Host: GitHub
• URL: https://github.com/pimutils/mates.rs
• Owner: pimutils
• License: mit
• Created: 2014-10-05T17:35:26.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2023-09-25T14:54:27.000Z (almost 3 years ago)
• Last Synced: 2025-05-31T16:11:58.644Z (about 1 year ago)
• Language: Rust
• Homepage:
• Size: 158 KB
• Stars: 64
• Watchers: 9
• Forks: 9
• Open Issues: 11
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Mates

[![Build status](https://travis-ci.org/pimutils/mates.rs.svg?branch=master)](https://travis-ci.org/pimutils/mates.rs)

A commandline addressbook. The main goals are:

- **High extensibility**

  - Mates operates on a directory of

    [vCard](https://tools.ietf.org/html/rfc6350) 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](https://aur.archlinux.org/packages/mates-git/) package from the

AUR.

For a manual installation, you need to have [Rust](http://www.rust-lang.org/)

and [Cargo](https://crates.io/) 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-/out/`.

## 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  complete-query

    bind editor ^T    complete

#### Create new contact from message

    # ~/.muttrc

    macro index,pager A \

        "mates add | xargs sh -c 'mates edit \"$@\" < /dev/tty || rm -v \"$@\"' mates" \

        "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

the mates editor. If you hit Ctrl-C, the contact will be deleted.

### Using fuzzy finders for email selection

[selecta](https://github.com/garybernhardt/selecta) and

[fzf](https://github.com/junegunn/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](https://vdirsyncer.readthedocs.org/) 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.