path: root/contrib/caldav/README

calcurse-caldav
===============

calcurse-caldav is a simple Python script that can be used to synchronize
calcurse with a CalDAV server. Please note that the script is alpha software!
This means that:

* We are eagerly looking for testers to run the script and give feedback! If
  you find any bugs, please report them to the calcurse mailing lists or to the
  GitHub bug tracker. If the script works fine for you, please report back as
  well!

* The script might still have bugs. MAKE BACKUPS, especially before running
  calcurse-caldav for the first time!

Usage
-----

calcurse-caldav requires an up-to-date version of calcurse and a configuration
file located at ~/.calcurse/caldav/config. An example configuration file can be
found under contrib/caldav/config.sample in the calcurse source tree. You will
also need to install *httplib2* for Python 3 using *pip* (e.g. `pip3 install
--user httplib2`) or your distribution's package manager.

If you run calcurse-caldav for the first time, you need to provide the --init
argument. You can choose between the following initialization modes:

    --init=keep-remote Remove all local calcurse items and import remote objects
    --init=keep-local  Remove all remote objects and push local calcurse items
    --init=two-way     Copy local objects to the CalDAV server and vice versa

For subsequent calcurse-caldav invocations, you don't need to specify any
additional parameters.

Hooks
-----

You can place scripts in `$HOME/.calcurse/caldav/hooks/` to trigger actions at
certain events. To enable a hook, add a script with one of the following names
to this directory. Also make sure the scripts are executable.

*pre-sync*::
  Executed before the data files are synchronized.
*post-sync*::
  Executed after the data files are synchronized.

Some examples can be found in the `contrib/caldav/hooks/` directory of the
calcurse source tree.

How It Works
------------

calcurse-caldav creates a so-called synchronization database at
~/.calcurse/caldav/sync.db that always keeps a snapshot of the last time the
script was executed. When running the script, it compares the objects on the
server and the local objects with that snapshot to identify items that were
added or deleted. It then

* downloads new objects from the server and imports them into calcurse,
* deletes local objects that no longer exist on the server,
* uploads objects to the server that were added locally,
* deleted objects from the server that were deleted locally,
* updates the synchronization database with a new snapshot.

Note: Since calcurse does not use unique identifiers for items, it cannot keep
track of moved/edited items. Thus, modifying an item is equivalent to deleting
the old item and creating a new one.