========
Tutorial
========

Installation
============

 - Make sure you have Python 2.7+ or Python 3.3+ installed.

 - ``pip install --user vdirsyncer``.

 - Check if the ``vdirsyncer`` command is available.

Configuration
=============

.. note::
    The `example.cfg from the repository
    <https://github.com/untitaker/vdirsyncer/blob/master/example.cfg>`_
    contains a very terse version of this.

By default, *vdirsyncer* looks for its configuration file at
``~/.vdirsyncer/config``. You can use the ``VDIRSYNCER_CONFIG`` environment
variable to change this path.

::
    [general]
    status_path = ~/.vdirsyncer/status/

The config file should start with the *general section*, where the only required
parameter is ``status_path``.The supported parameters are:

 - ``status_path``: A directory where vdirsyncer will store metadata for the
   next sync. The data is needed to determine whether a new item means it has
   been added on one side or deleted on the other.

 - ``processes`` defines the amount of maximal connections to use for syncing.
   By default there is no limit, which means vdirsyncer will try to open a
   connection for each collection to be synced. The value ``0`` is ignored.
   Setting this to ``1`` will only synchronize one collection at a time.
   
   While this often greatly increases performance, you might have valid reasons
   to set this to a smaller number. For example, your DAV server running on a
   Raspberry Pi is so slow that multiple connections don't help much, since the
   CPU and not the network is the bottleneck.

After the general section, an arbitrary amount of *pair and storage sections*
might come.

A *pair* section defines two storages ``a`` and ``b`` which should be
synchronized. The definition of these storages follows in *storage* sections.
This format is copied from OfflineIMAP, where storages are called repositories
and pairs are called accounts.

The following example synchronizes a single CardDAV-addressbook to
``~/.contacts/``::

    [pair my_contacts]
    a = my_contacts_local
    b = my_contacts_remote

    [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

After running ``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, and your changes will be
synchronized to the CalDAV server after you run ``vdirsyncer sync`` again. For
further reference, it uses the storages
:py:class:`vdirsyncer.storage.FilesystemStorage` and
:py:class:`vdirsyncer.storage.CarddavStorage`.

But what if we want to synchronize multiple addressbooks from the same server?
Of course we could create new pairs and storages for each addressbook, but that
is very tedious to do. Instead we will use a shortcut:

  - Remove the last segment from the URL, so that it ends with ``.../bob/``
    instead of ``.../bob/default/``.

  - Add the following line to the *pair* section::
    
        [pair my_contacts]
        ...
        collections = default,work

This will synchronize
``https://owncloud.example.com/remote.php/carddav/addressbooks/bob/default/``
with ``~/.contacts/default/`` and
``https://owncloud.example.com/remote.php/carddav/addressbooks/bob/work/`` with
``~/.contacts/work/``. Under the hood, vdirsyncer also just copies the pairs
and storages for each collection and appends the collection name to the path or
URL.

It almost seems like it could work. But 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.

Calendar sync works almost the same. Just swap ``type = carddav`` for ``type =
caldav`` and ``fileext = .vcf`` for ``fileext = .ics``.