diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 2c211e7..ac60624 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,7 +14,8 @@ Version 0.14.0 - ``vdirsyncer sync`` now continues other uploads if one upload failed. The exit code in such situations is still non-zero. -- Add ``partial_sync`` option to pair section. +- Add ``partial_sync`` option to pair section. See :ref:`the config docs + `. Version 0.13.1 ============== diff --git a/docs/config.rst b/docs/config.rst index 8b12bd6..4c76469 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -101,13 +101,18 @@ Pair Section Vdirsyncer never attempts to "automatically merge" the two items. +.. _partial_sync_def: + - ``partial_sync``: Assume A is read-only, B not. If you change items on B, vdirsyncer can't sync the changes to A. What should happen instead? - ``error``: An error is shown. - - ``ignore``: The change is ignored. + - ``ignore``: The change is ignored. However: Events deleted in B still + reappear if they're updated in A. - ``revert`` (default): The change is reverted on next sync. + See also :ref:`partial_sync_tutorial`. + - ``metadata``: Metadata keys that should be synchronized when ``vdirsyncer metasync`` is executed. Example:: diff --git a/docs/index.rst b/docs/index.rst index d9188c8..84b9a43 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ It aims to be for CalDAV and CardDAV what `OfflineIMAP tutorial ssl-tutorial keyring + partial-sync config supported problems diff --git a/docs/partial-sync.rst b/docs/partial-sync.rst new file mode 100644 index 0000000..1c776a9 --- /dev/null +++ b/docs/partial-sync.rst @@ -0,0 +1,72 @@ +.. _partial_sync_tutorial: + +=============================== +Syncing with read-only storages +=============================== + +If you want to subscribe to a public, read-only `WebCAL +`_-calendar but neither your server nor +your calendar apps support that (or support it insufficiently), vdirsyncer can +be used to synchronize such a public calendar ``A`` with a new calendar ``B`` +of your own and keep ``B`` updated. + +Step 1: Create the target calendar +================================== + +First you need to create the calendar you want to sync the WebCAL-calendar +with. Most servers offer a web interface for this. You then need to note the +CalDAV URL of your calendar. Note that this URL should directly point to the +calendar you just created, which means you would have one such URL for each +calendar you have. + +Step 2: Creating the config +=========================== + +Paste this into your vdirsyncer config:: + + [pair holidays] + a = holidays_public + b = holidays_private + collections = null + + [storage holidays_public] + type = http + # The URL to your iCalendar file. + url = ... + + [storage holidays_private] + type = caldav + # The direct URL to your calendar. + url = ... + # The credentials to your CalDAV server + username = ... + password = ... + +Then run ``vdirsyncer discover holidays`` and ``vdirsyncer sync holidays``, and +your previously created calendar should be filled with events. + +Step 3: The partial_sync parameter +================================== + +.. versionadded:: 0.14 + +You may get into a situation where you want to hide or modify some events from +your ``holidays`` calendar. If you try to do that at this point, you'll notice +that vdirsyncer will revert any changes you've made after a few times of +running ``sync``. This is because vdirsyncer wants to keep everything in sync, +and it can't synchronize changes to the public holidays-calendar because it +doesn't have the rights to do so. + +For such purposes you can set the ``partial_sync`` parameter to ``ignore``:: + + [pair holidays] + a = holidays_public + b = holidays_private + collections = null + partial_sync = ignore + +See :ref:`the config docs ` for more information. + +.. _nextCloud: https://nextcloud.com/ +.. _Baikal: http://sabre.io/baikal/ +.. _DAViCal: http://www.davical.org/