1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
|
=========================
Full configuration manual
=========================
Vdirsyncer uses an ini-like format for storing its configuration. All values
are JSON, invalid JSON will get interpreted as string::
x = "foo" # String
x = foo # Shorthand for same string
x = 42 # Integer
x = ["a", "b", "c"] # List of strings
x = true # Boolean
x = false
x = null # Also known as None
.. _general_config:
General Section
===============
::
[general]
status_path = ...
- ``status_path``: A directory where vdirsyncer will store some additional data
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. Relative paths will be interpreted as
relative to the configuration file's directory.
See `A simple synchronization algorithm
<https://unterwaditzer.net/2016/sync-algorithm.html>`_ for what exactly is in
there.
.. _pair_config:
Pair Section
============
::
[pair pair_name]
a = ...
b = ...
#collections = null
#conflict_resolution = null
- Pair names can consist of any alphanumeric characters and the underscore.
- ``a`` and ``b`` reference the storages to sync by their names.
- ``collections``: A list of collections to synchronize when ``vdirsyncer
sync`` is executed. See also :ref:`collections_tutorial`.
The special values ``"from a"`` and ``"from b"``, tell vdirsyncer to try
autodiscovery on a specific storage.
If the collection you want to sync doesn't have the same name on each side,
you may also use a value of the form ``["config_name", "name_a", "name_b"]``.
This will synchronize the collection ``name_a`` on side A with the collection
``name_b`` on side B. The ``config_name`` will be used for representation in
CLI arguments and logging.
Examples:
- ``collections = ["from b", "foo", "bar"]`` makes vdirsyncer synchronize the
collections from side B, and also the collections named "foo" and "bar".
- ``collections = ["from b", "from a"]`` makes vdirsyncer synchronize all
existing collections on either side.
- ``collections = [["bar", "bar_a", "bar_b"], "foo"]`` makes vdirsyncer
synchronize ``bar_a`` from side A with ``bar_b`` from side B, and also
synchronize ``foo`` on both sides with each other.
- ``conflict_resolution``: Optional, define how conflicts should be handled. A
conflict occurs when one item (event, task) changed on both sides since the
last sync. See also :ref:`conflict_resolution_tutorial`.
Valid values are:
- ``null``, where an error is shown and no changes are done.
- ``"a wins"`` and ``"b wins"``, where the whole item is taken from one side.
- ``["command", "vimdiff"]``: ``vimdiff <a> <b>`` will be called where
``<a>`` and ``<b>`` are temporary files that contain the item of each side
respectively. The files need to be exactly the same when the command
returns.
- ``vimdiff`` can be replaced with any other command. For example, in POSIX
``["command", "cp"]`` is equivalent to ``"a wins"``.
- Additional list items will be forwarded as arguments. For example,
``["command", "vimdiff", "--noplugin"]`` runs ``vimdiff --noplugin``.
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. 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::
metadata = ["color", "displayname"]
This synchronizes the ``color`` and the ``displayname`` properties. The
``conflict_resolution`` parameter applies here as well.
.. _storage_config:
Storage Section
===============
::
[storage storage_name]
type = ...
- Storage names can consist of any alphanumeric characters and the underscore.
- ``type`` defines which kind of storage is defined. See :ref:`storages`.
- ``read_only`` defines whether the storage should be regarded as a read-only
storage. The value ``true`` means synchronization will discard any changes
made to the other side. The value ``false`` implies normal 2-way
synchronization.
- Any further parameters are passed on to the storage class.
.. _storages:
Supported Storages
------------------
CalDAV and CardDAV
++++++++++++++++++
.. autostorage:: vdirsyncer.storage.dav.CalDAVStorage
.. autostorage:: vdirsyncer.storage.dav.CardDAVStorage
Google
++++++
At first run you will be asked to authorize application for google account
access.
To use this storage type, you need to install some additional dependencies::
pip install vdirsyncer[google]
Furthermore you need to register vdirsyncer as an application yourself to
obtain ``client_id`` and ``client_secret``, as `it is against Google's Terms of
Service to hardcode those into opensource software
<https://developers.google.com/terms/?hl=th#b-confidential-matters>`_:
1. Go to the `Google API Manager <https://console.developers.google.com>`_ and
create a new project under any name.
2. Within that project, enable the "CalDAV" and "CardDAV" APIs (**not** the
Calendar and Contacts APIs, those are different and won't work). There should
be a searchbox where you can just enter those terms.
3. In the sidebar, select "Credentials" and create a new "OAuth Client ID". The
application type is "Other".
You'll be prompted to create a OAuth consent screen first. Fill out that
form however you like.
4. Finally you should have a Client ID and a Client secret. Provide these in
your storage config.
You can select which calendars to sync on `CalDav settings page
<https://calendar.google.com/calendar/syncselect>`_.
.. autostorage:: vdirsyncer.storage.google.GoogleCalendarStorage
.. autostorage:: vdirsyncer.storage.google.GoogleContactsStorage
remoteStorage
+++++++++++++
`remoteStorage <https://remotestorage.io/>`_ is an open per-user data storage
protocol. Vdirsyncer contains **highly experimental support** for it.
.. note::
Do not use this storage if you're not prepared for data-loss and breakage.
To use them, you need to install some optional dependencies with::
pip install vdirsyncer[remotestorage]
.. autostorage:: vdirsyncer.storage.remotestorage.RemoteStorageContacts
.. autostorage:: vdirsyncer.storage.remotestorage.RemoteStorageCalendars
Local
+++++
.. autostorage:: vdirsyncer.storage.filesystem.FilesystemStorage
.. autostorage:: vdirsyncer.storage.singlefile.SingleFileStorage
Read-only storages
++++++++++++++++++
These storages don't support writing of their items, consequently ``read_only``
is set to ``true`` by default. Changing ``read_only`` to ``false`` on them
leads to an error.
.. autostorage:: vdirsyncer.storage.http.HttpStorage
|
