
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" for "type =
    caldav" and "fileext = .vcf" for "fileext = .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.
