Tutorial¶
Before starting, consider if you actually need vdirsyncer. There are better alternatives available for particular usecases.
Installation¶
Unless you want to contribute to vdirsyncer, you should use the packages from your distribution:
- ArchLinux (AUR)
- pkgsrc
- Fedora
- nixpkg
- GNU Guix
- homebrew
- Gentoo
- Debian and Ubuntu don’t have packages, but make a manual installation especially hard. See Requests-related ImportErrors on Debian-based distributions.
If there is no package for your distribution, you’ll need to install vdirsyncer manually. There is an easy command to copy-and-paste for this as well, but you should be aware of its consequences.
Configuration¶
Note
- The config.example from the repository contains a very terse version of this.
- In this example we set up contacts synchronization, but calendar sync
works almost the same. Just swap
type = carddav
fortype = caldav
andfileext = .vcf
forfileext = .ics
. - Take a look at the Known Problems page if anything doesn’t work like planned.
By default, vdirsyncer looks for its configuration file in the following locations:
- The file pointed to by the
VDIRSYNCER_CONFIG
environment variable. ~/.vdirsyncer/config
.$XDG_CONFIG_HOME/vdirsyncer/config
, which is normally~/.config/vdirsyncer/config
. See the XDG-Basedir specification.
The config file should start with a general section,
where the only required parameter is status_path
. The following is a
minimal example:
[general]
status_path = ~/.vdirsyncer/status/
After the general section, an arbitrary amount of pair and storage sections might come.
In vdirsyncer, synchronization is always done between two storages. Such storages are defined in storage sections, and which pairs of storages should actually be synchronized is defined in pair section. This format is copied from OfflineIMAP, where storages are called repositories and pairs are called accounts.
The following example synchronizes ownCloud’s
default addressbook to ~/.contacts/
:
[pair my_contacts]
a = my_contacts_local
b = my_contacts_remote
collections = null
[storage my_contacts_local]
type = filesystem
path = ~/.contacts/
fileext = .vcf
[storage my_contacts_remote]
type = carddav
url = https://owncloud.example.com/remote.php/carddav/addressbooks/bob/default/
username = bob
password = asdf
Note
Configuration for other servers can be found at Supported servers.
After running vdirsyncer discover
and vdirsyncer sync
, ~/.contacts/
will contain a bunch of .vcf
files which all contain a contact in VCARD
format each. You can modify their content, add new ones and delete some [1],
and your changes will be synchronized to the CalDAV server after you run
vdirsyncer sync
again. For further reference, it uses the storages
filesystem
and carddav
.
[1] | You’ll want to use a helper program for this. |
More Configuration¶
Conflict resolution¶
What if the same item is changed on both sides? What should vdirsyncer do? By default, it will show an ugly error message, which is surely a way to avoid the problem. Another way to solve that ambiguity is to add another line to the pair section:
[pair my_contacts]
...
conflict_resolution = b wins
Earlier we wrote that b = my_contacts_remote
, so when vdirsyncer encounters
the situation where an item changed on both sides, it will simply overwrite the
local item with the one from the server. Of course a wins
is also a valid
value.
Collection discovery¶
The above configuration only syncs a single addressbook. This is denoted by
collections = null
(collection = addressbook/calendar). We can change this
line to let vdirsyncer automatically sync all addressbooks it can find:
[pair my_contacts]
a = my_contacts_local
b = my_contacts_remote
collections = ["from a", "from b"] # changed from `null`
[storage my_contacts_local]
type = filesystem
path = ~/.contacts/
fileext = .vcf
[storage my_contacts_remote]
type = carddav
# We can simplify this URL here as well. In theory it shouldn't matter.
url = https://owncloud.example.com/remote.php/carddav/
username = bob
password = asdf
With the above configuration, vdirsyncer discover
will fetch all available
collections from the server, and create subdirectories for each of them in
~/.contacts/
after confirmation. For example, ownCloud’s default
addressbook "default"
would be synchronized to the location
~/.contacts/default/
.
After that, vdirsyncer sync
will synchronize all your addressbooks as
expected. However, if new collections are created on the server, it will not
automatically start synchronizing those [2]. You need to run vdirsyncer
discover
again to re-fetch this list instead.
[2] | Because collections are added rarely, and checking for this case before every synchronization isn’t worth the overhead. |
Metadata synchronization¶
Besides items, vdirsyncer can also synchronize metadata like the addressbook’s or calendar’s “human-friendly” name (internally called “displayname”) or the color associated with a calendar. For the purpose of explaining this feature, let’s switch to a different base example. This time we’ll synchronize calendars:
[pair my_calendars]
a = my_calendars_local
b = my_calendars_remote
collections = ["from a", "from b"]
metadata = ["color"]
[storage my_calendars_local]
type = filesystem
path = ~/.calendars/
fileext = .ics
[storage my_calendars_remote]
type = caldav
url = https://owncloud.example.com/remote.php/caldav/
username = bob
password = asdf
Run vdirsyncer discover
for discovery. Then you can use vdirsyncer
metasync
to synchronize the color
property between your local calendars
in ~/.calendars/
and your ownCloud. Locally the color is just represented
as a file called color
within the calendar folder.