Introduction

pimsync synchronises documentation across storages. Currently supported storages are:

• CalDAV: HTTP extension which provides read and write access to calendars on servers.

• CardDAV: HTTP extension which provides read and write access to address books on servers.

• Vdir: Convention for storing calendars and address books in local directories using standardised and well-documented formats.

• WebCal: Convention for exposing a calendar or event read-only using HTTP.

Philosophy

Synchronise items regardless of whether they are valid or not

If another program created a “technically invalid” calendar event, the data needs to be synchronised anyway in order for it to be accessible to the user. The user is then empowered to either fix the invalidity, or handle the file with some other tools which can handle the “technically invalid” quirks properly.

Use standards protocols, formats and conventions whenever possible.

Calendar components are stored using the iCalendar format. Contacts are stored using the vCard format. CalDAV and CardDAV are well established protocols which many implementations (including ones which anyone can self-host) and service providers.

Do one thing, do it well

Don’t focus on seemingly related functionality; let external tools implement other features and provide the means for them to interoperate. Doing less usually leads to greater flexibility.

Provide clear instructions

Focus on clear documentation and explaining how things work. Avoid guessing what the user wanted when it can lead to unexpected outcomes. Allow anyone to understand how things work to the level of detail with which they are comfortable.

Comparison to vdirsyncer

pimsync grew out of lessons learnt from vdirsyncer, a previous incarnation of the same tool. Key differences are:

Focuses on good error management and recovery

If synchronising a single item fails (e.g.: because a server rejects it), the overall operation continues, and other items in the same collection are synchronised properly.

This is made much easier to achieve due to our use of Rust and how error branches and handled in Rust.

The daemon subcommand

Runs continuously in the keeping collections in sync. Ideal for usage as a service.

Synchronise collections

Automatically create (and, optionally, delete) collections which are created (and deleted) on one storage into the other.

Simplified setup

Being built in Rust, pimsync can be compiled into a single binary. This substantially simplifies the installation process, and also provide improved performance.

A few features present in vdirsyncer are still missing from pimsync. For details on these and changes required when migrating, see the migration manual page