Skip to main content


Combine multiple aerc-style address books into a single, unified address book. The unified address book contains no duplicate email addresses, and the addresses are sorted based on the order of the books, the order of the addresses within the books, and the optional ranks assigned to addresses.

Using it in aerc

With addr-book-combine, I can simultaneously use my contacts (stored in khard) and the results of maildir-rank-addr for auto-completion in the aerc email client. Here’s a snippet from my aerc config:

address-book-cmd = addr-book-combine \
                       -c "khard email --remove-first-line --parsable '%s'" \
                       -c "rg -F -i -- '%s' ~/.ranked-addrs.tsv"

How sorting works

When comparing two addresses, the following procedure is applied:

  1. First, if the addresses are not from the same book, the address from the earlier book appears first.

  2. Next, each book is checked to compare the addresses:

    • If neither address is ranked within the book, check in the next book.
    • If only one address is ranked within the book, the ranked address appears first.
    • If both addresses have the same rank, check in the next book.
    • If the addresses have different ranks, the address with the lowest rank appears first.
  3. Finally, if no address has been chosen to appear first, preserve the original order of the addresses.

Check out the test code to see some examples.

Example input/output

Here’s an example of addr-book-combine in action:

$ cat book1.tsv	Andy Apple	1	Bart Berry	Chad Cherry	5	Dale Donut

$ cat book2.tsv	D. Donut	4	Andy Apple	2	Eric Egg	Fred Fig

$ addr-book-combine -f book1.tsv -f book2.tsv	Andy Apple	0	Chad Cherry	1	Dale Donut	2	Bart Berry	3	Eric Egg	4	Fred Fig	4

Source code and documentation are available in the Git repository.

Contributions are welcome! You can send questions, bug reports, patches, etc. by email to ~jcc/

[This page was last updated on December 7, 2022]