1VDIRSYNCER(1) vdirsyncer VDIRSYNCER(1)
2
6 vdirsyncer - vdirsyncer Documentation
7 • Documentation
9 • Source code
11 Vdirsyncer is a command-line tool for synchronizing calendars and ad‐
13 dressbooks between a variety of servers and the local filesystem. The
14 most popular usecase is to synchronize a server with a local folder and
15 use a set of other programs to change the local events and contacts.
16 Vdirsyncer can then synchronize those changes back to the server.
17 However, vdirsyncer is not limited to synchronizing between clients and
19 servers. It can also be used to synchronize calendars and/or address‐
20 books between two servers directly.
21 It aims to be for calendars and contacts what OfflineIMAP is for
23 emails.
24
26 Why not Dropbox + todo.txt?
27 Projects like todo.txt criticize the complexity of modern productivity
28 apps, and that rightfully. So they set out to create a new, super-sim‐
29 ple, human-readable format, such that vim suffices for viewing the raw
30 data. However, when they're faced with the question how to synchronize
31 that data across multiple devices, they seemed to have reached the dead
32 end with their novel idea: "Let's just use Dropbox".
33 What does file sync software do if both files have changed since the
35 last sync? The answer is to ignore the question, just sync as often as
36 possible, and hope for the best. Because if it comes to a sync con‐
37 flict, most sync services are not daring to merge files, and create two
38 copies on each computer instead. Merging the two task lists is left to
39 the user.
40 A better idea would've been to use git to synchronize the todo.txt
42 file, which is at least able to resolve some basic conflicts.
43 Why not file sync (Dropbox, git, ...) + vdir?
45 Since vdirs are just a bunch of files, it is obvious to try file syn‐
46 chronization for synchronizing your data between multiple computers,
47 such as:
48 • Syncthing
50 • Dropbox or one of the gajillion services like it
52 • unison
54 • Just git with a sshd.
56 The disadvantages of those solutions largely depend on the exact file
58 sync program chosen:
59 • Like with todo.txt, Dropbox and friends are obviously agnostic/un‐
61 aware of the files' contents. If a file has changed on both sides,
62 Dropbox just copies both versions to both sides.
63 This is a good idea if the user is directly interfacing with the file
65 system and is able to resolve conflicts themselves. Here it might
66 lead to erroneous behavior with e.g. khal, since there are now two
67 events with the same UID.
68 This point doesn't apply to git: It has very good merging capabili‐
70 ties, better than what vdirsyncer currently has.
71 • Such a setup doesn't work at all with smartphones. Vdirsyncer, on the
73 other hand, synchronizes with CardDAV/CalDAV servers, which can be
74 accessed with e.g. DAVx⁵ or the apps by dmfs.
75
77 OS/distro packages
78 The following packages are user-contributed and were up-to-date at the
79 time of writing:
80 • ArchLinux
82 • Ubuntu and Debian, x86_64-only (packages also exist in the official
84 repositories but may be out of date)
85 • GNU Guix
87 • OS X (homebrew)
89 • BSD (pkgsrc)
91 • OpenBSD
93 We only support the latest version of vdirsyncer, which is at the time
95 of this writing 0.18.0. Please do not file bugs if you use an older
96 version.
97 Some distributions have multiple release channels. Debian and Fedora
99 for example have a "stable" release channel that ships an older version
100 of vdirsyncer. Those versions aren't supported either.
101 If there is no suitable package for your distribution, you'll need to
103 install vdirsyncer manually. There is an easy command to copy-and-paste
104 for this as well, but you should be aware of its consequences.
105 Manual installation
107 If your distribution doesn't provide a package for vdirsyncer, you
108 still can use Python's package manager "pip". First, you'll have to
109 check that the following things are installed:
110 • Python 3.7+ and pip.
112 • libxml and libxslt
114 • zlib
116 • Linux or OS X. Windows is not supported, see issue #535.
118 On Linux systems, using the distro's package manager is the best way to
120 do this, for example, using Ubuntu:
121 sudo apt-get install libxml2 libxslt1.1 zlib1g python
123 Then you have several options. The following text applies for most
125 Python software by the way.
126 The dirty, easy way
128 The easiest way to install vdirsyncer at this point would be to run:
129 pip install --user --ignore-installed vdirsyncer
131 • --user is to install without root rights (into your home directory)
133 • --ignore-installed is to work around Debian's potentially broken
135 packages (see Requests-related ImportErrors).
136 This method has a major flaw though: Pip doesn't keep track of the
138 files it installs. Vdirsyncer's files would be located somewhere in
139 ~/.local/lib/python*, but you can't possibly know which packages were
140 installed as dependencies of vdirsyncer and which ones were not, should
141 you decide to uninstall it. In other words, using pip that way would
142 pollute your home directory.
143 The clean, hard way
145 There is a way to install Python software without scattering stuff
146 across your filesystem: virtualenv. There are a lot of resources on how
147 to use it, the simplest possible way would look something like:
148 virtualenv ~/vdirsyncer_env
150 ~/vdirsyncer_env/bin/pip install vdirsyncer
151 alias vdirsyncer="~/vdirsyncer_env/bin/vdirsyncer"
152 You'll have to put the last line into your .bashrc or .bash_profile.
154 This method has two advantages:
156 • It separately installs all Python packages into ~/vdirsyncer_env/,
158 without relying on the system packages. This works around OS- or dis‐
159 tro-specific issues.
160 • You can delete ~/vdirsyncer_env/ to uninstall vdirsyncer entirely.
162 The clean, easy way
164 pipx is a new package manager for Python-based software that automati‐
165 cally sets up a virtualenv for each program you install. Assuming you
166 have it installed on your operating system, you can do:
167 pipx install vdirsyncer
169 and ~/.local/pipx/venvs/vdirsyncer will be your new vdirsyncer instal‐
171 lation. To update vdirsyncer to the latest version:
172 pipx upgrade vdirsyncer
174 If you're done with vdirsyncer, you can do:
176 pipx uninstall vdirsyncer
178 and vdirsyncer will be uninstalled, including its dependencies.
180
182 Before starting, consider if you actually need vdirsyncer. There are
183 better alternatives available for particular usecases.
184 Installation
186 See Installation.
187 Configuration
189 NOTE:
190 • The config.example from the repository contains a very terse ver‐
192 sion of this.
193 • In this example we set up contacts synchronization, but calendar
195 sync works almost the same. Just swap type = "carddav" for type =
196 "caldav" and fileext = ".vcf" for fileext = ".ics".
197 • Take a look at the Known Problems page if anything doesn't work
199 like planned.
200 By default, vdirsyncer looks for its configuration file in the follow‐
202 ing locations:
203 • The file pointed to by the VDIRSYNCER_CONFIG environment variable.
205 • ~/.vdirsyncer/config.
207 • $XDG_CONFIG_HOME/vdirsyncer/config, which is normally ~/.con‐
209 fig/vdirsyncer/config. See the XDG-Basedir specification.
210 The config file should start with a general section, where the only re‐
212 quired parameter is status_path. The following is a minimal example:
213 [general]
215 status_path = "~/.vdirsyncer/status/"
216 After the general section, an arbitrary amount of pair and storage sec‐
218 tions might come.
219 In vdirsyncer, synchronization is always done between two storages.
221 Such storages are defined in storage sections, and which pairs of stor‐
222 ages should actually be synchronized is defined in pair section. This
223 format is copied from OfflineIMAP, where storages are called reposito‐
224 ries and pairs are called accounts.
225 The following example synchronizes ownCloud's addressbooks to ~/.con‐
227 tacts/:
228 [pair my_contacts]
230 a = "my_contacts_local"
231 b = "my_contacts_remote"
232 collections = ["from a", "from b"]
233 [storage my_contacts_local]
235 type = "filesystem"
236 path = "~/.contacts/"
237 fileext = ".vcf"
238 [storage my_contacts_remote]
240 type = "carddav"
241 # We can simplify this URL here as well. In theory it shouldn't matter.
243 url = "https://owncloud.example.com/remote.php/carddav/"
244 username = "bob"
245 password = "asdf"
246 NOTE:
248 Configuration for other servers can be found at Servers.
249 After running vdirsyncer discover and vdirsyncer sync, ~/.contacts/
251 will contain subfolders for each addressbook, which in turn will con‐
252 tain a bunch of .vcf files which all contain a contact in VCARD format
253 each. You can modify their contents, add new ones and delete some [1],
254 and your changes will be synchronized to the CalDAV server after you
255 run vdirsyncer sync again. For further reference, it uses the storages
256 filesystem and carddav.
257 However, if new collections are created on the server, it will not au‐
259 tomatically start synchronizing those [2]. You need to run vdirsyncer
260 discover again to re-fetch this list instead.
261 [1] You'll want to use a helper program for this.
263 [2] Because collections are added rarely, and checking for this case
265 before every synchronization isn't worth the overhead.
266 More Configuration
268 Conflict resolution
269 What if the same item is changed on both sides? What should vdirsyncer
270 do? Three options are currently provided:
271 1. vdirsyncer displays an error message (the default);
273 2. vdirsyncer chooses one alternative version over the other;
275 3. vdirsyncer starts a command of your choice that is supposed to merge
277 the two alternative versions.
278 Options 2 and 3 require adding a "conflict_resolution" parameter to the
280 pair section. Option 2 requires giving either "a wins" or "b wins" as
281 value to the parameter:
282 [pair my_contacts]
284 ...
285 conflict_resolution = "b wins"
286 Earlier we wrote that b = "my_contacts_remote", so when vdirsyncer en‐
288 counters the situation where an item changed on both sides, it will
289 simply overwrite the local item with the one from the server.
290 Option 3 requires specifying as value of "conflict_resolution" an array
292 starting with "command" and containing paths and arguments to a com‐
293 mand. For example:
294 [pair my_contacts]
296 ...
297 conflict_resolution = ["command", "vimdiff"]
298 In this example, vimdiff <a> <b> will be called with <a> and <b> being
300 two temporary files containing the conflicting files. The files need to
301 be exactly the same when the command returns. More arguments can be
302 passed to the command by adding more elements to the array.
303 See Pair Section for the reference documentation.
305 Metadata synchronization
307 Besides items, vdirsyncer can also synchronize metadata like the ad‐
308 dressbook's or calendar's "human-friendly" name (internally called
309 "displayname") or the color associated with a calendar. For the purpose
310 of explaining this feature, let's switch to a different base example.
311 This time we'll synchronize calendars:
312 [pair my_calendars]
314 a = "my_calendars_local"
315 b = "my_calendars_remote"
316 collections = ["from a", "from b"]
317 metadata = ["color"]
318 [storage my_calendars_local]
320 type = "filesystem"
321 path = "~/.calendars/"
322 fileext = ".ics"
323 [storage my_calendars_remote]
325 type = "caldav"
326 url = "https://owncloud.example.com/remote.php/caldav/"
328 username = "bob"
329 password = "asdf"
330 Run vdirsyncer discover for discovery. Then you can use vdirsyncer
332 metasync to synchronize the color property between your local calendars
333 in ~/.calendars/ and your ownCloud. Locally the color is just repre‐
334 sented as a file called color within the calendar folder.
335 More information about collections
337 "Collection" is a collective term for addressbooks and calendars. Each
338 collection from a storage has a "collection name", a unique identifier
339 for each collection. In the case of filesystem-storage, this is the
340 name of the directory that represents the collection, in the case of
341 the DAV-storages this is the last segment of the URL. We use this iden‐
342 tifier in the collections parameter in the pair-section.
343 This identifier doesn't change even if you rename your calendar in
345 whatever UI you have, because that only changes the so-called "display‐
346 name" property [3]. On some servers (iCloud, Google) this identifier
347 is randomly generated and has no correlation with the displayname you
348 chose.
349 [3] Which you can also synchronize with metasync using metadata =
351 ["displayname"].
352 There are three collection names that have a special meaning:
354 • "from a", "from b": A placeholder for all collections that can be
356 found on side A/B when running vdirsyncer discover.
357 • null: The parameters give to the storage are exact and require no
359 discovery.
360 The last one requires a bit more explanation. Assume this config which
362 synchronizes two directories of addressbooks:
363 [pair foobar]
365 a = "foo"
366 b = "bar"
367 collections = ["from a", "from b"]
368 [storage foo]
370 type = "filesystem"
371 fileext = ".vcf"
372 path = "./contacts_foo/"
373 [storage bar]
375 type = "filesystem"
376 fileext = ".vcf"
377 path = "./contacts_bar/"
378 As we saw previously this will synchronize all collections in ./con‐
380 tacts_foo/ with each same-named collection in ./contacts_bar/. If
381 there's a collection that exists on one side but not the other,
382 vdirsyncer will ask whether to create that folder on the other side.
383 If we set collections = null, ./contacts_foo/ and ./contacts_bar/ are
385 no longer treated as folders with collections, but as collections them‐
386 selves. This means that ./contacts_foo/ and ./contacts_bar/ will con‐
387 tain .vcf-files, not subfolders that contain .vcf-files.
388 This is useful in situations where listing all collections fails be‐
390 cause your DAV-server doesn't support it, for example. In this case,
391 you can set url of your carddav- or caldav-storage to a URL that points
392 to your CalDAV/CardDAV collection directly.
393 Note that not all storages support the null-collection, for example
395 google_contacts and google_calendar don't.
396 Advanced collection configuration (server-to-server sync)
398 The examples above are good enough if you want to synchronize a remote
399 server to a previously empty disk. However, even more trickery is re‐
400 quired when you have two servers with already existing collections
401 which you want to synchronize.
402 The core problem in this situation is that vdirsyncer pairs collections
404 by collection name by default (see definition in previous section, ba‐
405 sically a foldername or a remote UUID). When you have two servers,
406 those collection names may not line up as nicely. Suppose you created
407 two calendars "Test", one on a NextCloud server and one on iCloud, us‐
408 ing their respective web interfaces. The URLs look something like this:
409 NextCloud: https://example.com/remote.php/dav/calendars/user/test/
411 iCloud: https://p-XX.caldav.icloud.com/YYY/calendars/3b4c9995-5c67-4021-9fa0-be4633623e1c
412 Those are two DAV calendar collections. Their collection names will be
414 test and 3b4c9995-5c67-4021-9fa0-be4633623e1c respectively, so you
415 don't have a single name you can address them both with. You will need
416 to manually "pair" (no pun intended) those collections up like this:
417 [pair doublecloud]
419 a = "my_nextcloud"
420 b = "my_icloud"
421 collections = [["mytest", "test", "3b4c9995-5c67-4021-9fa0-be4633623e1c"]]
422 mytest gives that combination of calendars a nice name you can use when
424 talking about it, so you would use vdirsyncer sync doublecloud/mytest
425 to say: "Only synchronize these two storages, nothing else that may be
426 configured".
427 NOTE:
429 Why not use displaynames?
430 You may wonder why vdirsyncer just couldn't figure this out by it‐
432 self. After all, you did name both collections "Test" (which is
433 called "the displayname"), so why not pair collections by that
434 value?
435 There are a few problems with this idea:
437 • Two calendars may have the same exact displayname.
439 • A calendar may not have a (non-empty) displayname.
441 • The displayname might change. Either you rename the calendar, or
443 the calendar renames itself because you change a language setting.
444 In the end, that property was never designed to be parsed by ma‐
446 chines.
447
449 All SSL configuration is done per-storage.
450 Pinning by fingerprint
452 To pin the certificate by fingerprint:
453 [storage foo]
455 type = "caldav"
456 ...
457 verify_fingerprint = "94:FD:7A:CB:50:75:A4:69:82:0A:F8:23:DF:07:FC:69:3E:CD:90:CA"
458 #verify = false # Optional: Disable CA validation, useful for self-signed certs
459 SHA1-, SHA256- or MD5-Fingerprints can be used. They're detected by
461 their length.
462 You can use the following command for obtaining a SHA-1 fingerprint:
464 echo -n | openssl s_client -connect unterwaditzer.net:443 | openssl x509 -noout -fingerprint
466 Note that verify_fingerprint doesn't suffice for vdirsyncer to work
468 with self-signed certificates (or certificates that are not in your
469 trust store). You most likely need to set verify = false as well. This
470 disables verification of the SSL certificate's expiration time and the
471 existence of it in your trust store, all that's verified now is the
472 fingerprint.
473 However, please consider using Let's Encrypt such that you can forget
475 about all of that. It is easier to deploy a free certificate from them
476 than configuring all of your clients to accept the self-signed certifi‐
477 cate.
478 Custom root CAs
480 To point vdirsyncer to a custom set of root CAs:
481 [storage foo]
483 type = "caldav"
484 ...
485 verify = "/path/to/cert.pem"
486 Vdirsyncer uses the requests library, which, by default, uses its own
488 set of trusted CAs.
489 However, the actual behavior depends on how you have installed it. Many
491 Linux distributions patch their python-requests package to use the sys‐
492 tem certificate CAs. Normally these two stores are similar enough for
493 you to not care.
494 But there are cases where certificate validation fails even though you
496 can access the server fine through e.g. your browser. This usually in‐
497 dicates that your installation of the requests library is somehow bro‐
498 ken. In such cases, it makes sense to explicitly set verify or ver‐
499 ify_fingerprint as shown above.
500 Client Certificates
502 Client certificates may be specified with the auth_cert parameter. If
503 the key and certificate are stored in the same file, it may be a
504 string:
505 [storage foo]
507 type = "caldav"
508 ...
509 auth_cert = "/path/to/certificate.pem"
510 If the key and certificate are separate, a list may be used:
512 [storage foo]
514 type = "caldav"
515 ...
516 auth_cert = ["/path/to/certificate.crt", "/path/to/key.key"]
517
519 Changed in version 0.7.0: Password configuration got completely over‐
520 hauled.
521 Vdirsyncer can fetch passwords from several sources other than the con‐
524 fig file.
525 Command
527 Say you have the following configuration:
528 [storage foo]
530 type = "caldav"
531 url = ...
532 username = "foo"
533 password = "bar"
534 But it bugs you that the password is stored in cleartext in the config
536 file. You can do this:
537 [storage foo]
539 type = "caldav"
540 url = ...
541 username = "foo"
542 password.fetch = ["command", "~/get-password.sh", "more", "args"]
543 You can fetch the username as well:
545 [storage foo]
547 type = "caldav"
548 url = ...
549 username.fetch = ["command", "~/get-username.sh"]
550 password.fetch = ["command", "~/get-password.sh"]
551 Or really any kind of parameter in a storage section.
553 With pass for example, you might find yourself writing something like
555 this in your configuration file:
556 password.fetch = ["command", "pass", "caldav"]
558 Accessing the system keyring
560 As shown above, you can use the command strategy to fetch your creden‐
561 tials from arbitrary sources. A very common usecase is to fetch your
562 password from the system keyring.
563 The keyring Python package contains a command-line utility for fetching
565 passwords from the OS's password store. Installation:
566 pip install keyring
568 Basic usage:
570 password.fetch = ["command", "keyring", "get", "example.com", "foouser"]
572 Password Prompt
574 You can also simply prompt for the password:
575 [storage foo]
577 type = "caldav"
578 username = "myusername"
579 password.fetch = ["prompt", "Password for CalDAV"]
580
582 If you want to subscribe to a public, read-only WebCAL-calendar but
583 neither your server nor your calendar apps support that (or support it
584 insufficiently), vdirsyncer can be used to synchronize such a public
585 calendar A with a new calendar B of your own and keep B updated.
586 Step 1: Create the target calendar
588 First you need to create the calendar you want to sync the WebCAL-cal‐
589 endar with. Most servers offer a web interface for this. You then need
590 to note the CalDAV URL of your calendar. Note that this URL should di‐
591 rectly point to the calendar you just created, which means you would
592 have one such URL for each calendar you have.
593 Step 2: Creating the config
595 Paste this into your vdirsyncer config:
596 [pair holidays]
598 a = "holidays_public"
599 b = "holidays_private"
600 collections = null
601 [storage holidays_public]
603 type = "http"
604 # The URL to your iCalendar file.
605 url = "..."
606 [storage holidays_private]
608 type = "caldav"
609 # The direct URL to your calendar.
610 url = "..."
611 # The credentials to your CalDAV server
612 username = "..."
613 password = "..."
614 Then run vdirsyncer discover holidays and vdirsyncer sync holidays, and
616 your previously created calendar should be filled with events.
617 Step 3: The partial_sync parameter
619 New in version 0.14.
620 You may get into a situation where you want to hide or modify some
623 events from your holidays calendar. If you try to do that at this
624 point, you'll notice that vdirsyncer will revert any changes you've
625 made after a few times of running sync. This is because vdirsyncer
626 wants to keep everything in sync, and it can't synchronize changes to
627 the public holidays-calendar because it doesn't have the rights to do
628 so.
629 For such purposes you can set the partial_sync parameter to ignore:
631 [pair holidays]
633 a = "holidays_public"
634 b = "holidays_private"
635 collections = null
636 partial_sync = ignore
637 See the config docs for more information.
639
641 Vdirsyncer uses an ini-like format for storing its configuration. All
642 values are JSON, invalid JSON will get interpreted as string:
643 x = "foo" # String
645 x = foo # Shorthand for same string
646 x = 42 # Integer
648 x = ["a", "b", "c"] # List of strings
650 x = true # Boolean
652 x = false
653 x = null # Also known as None
655 General Section
657 [general]
658 status_path = ...
659 • status_path: A directory where vdirsyncer will store some additional
661 data for the next sync.
662 The data is needed to determine whether a new item means it has been
664 added on one side or deleted on the other. Relative paths will be in‐
665 terpreted as relative to the configuration file's directory.
666 See A simple synchronization algorithm for what exactly is in there.
668 Pair Section
670 [pair pair_name]
671 a = ...
672 b = ...
673 #collections = null
674 #conflict_resolution = null
675 • Pair names can consist of any alphanumeric characters and the under‐
677 score.
678 • a and b reference the storages to sync by their names.
680 • collections: A list of collections to synchronize when vdirsyncer
682 sync is executed. See also More information about collections.
683 The special values "from a" and "from b", tell vdirsyncer to try au‐
685 todiscovery on a specific storage.
686 If the collection you want to sync doesn't have the same name on each
688 side, you may also use a value of the form ["config_name", "name_a",
689 "name_b"]. This will synchronize the collection name_a on side A
690 with the collection name_b on side B. The config_name will be used
691 for representation in CLI arguments and logging.
692 Examples:
694 • collections = ["from b", "foo", "bar"] makes vdirsyncer synchronize
696 the collections from side B, and also the collections named "foo"
697 and "bar".
698 • collections = ["from b", "from a"] makes vdirsyncer synchronize all
700 existing collections on either side.
701 • collections = [["bar", "bar_a", "bar_b"], "foo"] makes vdirsyncer
703 synchronize bar_a from side A with bar_b from side B, and also syn‐
704 chronize foo on both sides with each other.
705 • conflict_resolution: Optional, define how conflicts should be han‐
707 dled. A conflict occurs when one item (event, task) changed on both
708 sides since the last sync. See also Conflict resolution.
709 Valid values are:
711 • null, where an error is shown and no changes are done.
713 • "a wins" and "b wins", where the whole item is taken from one side.
715 • ["command", "vimdiff"]: vimdiff <a> <b> will be called where <a>
717 and <b> are temporary files that contain the item of each side re‐
718 spectively. The files need to be exactly the same when the command
719 returns.
720 • vimdiff can be replaced with any other command. For example, in
722 POSIX ["command", "cp"] is equivalent to "a wins".
723 • Additional list items will be forwarded as arguments. For exam‐
725 ple, ["command", "vimdiff", "--noplugin"] runs vimdiff --noplu‐
726 gin.
727 Vdirsyncer never attempts to "automatically merge" the two items.
729 • partial_sync: Assume A is read-only, B not. If you change items on B,
731 vdirsyncer can't sync the changes to A. What should happen instead?
732 • error: An error is shown.
734 • ignore: The change is ignored. However: Events deleted in B still
736 reappear if they're updated in A.
737 • revert (default): The change is reverted on next sync.
739 See also Syncing with read-only storages.
741 • metadata: Metadata keys that should be synchronized when vdirsyncer
743 metasync is executed. Example:
744 metadata = ["color", "displayname"]
746 This synchronizes the color and the displayname properties. The con‐
748 flict_resolution parameter applies here as well.
749 Storage Section
751 [storage storage_name]
752 type = ...
753 • Storage names can consist of any alphanumeric characters and the un‐
755 derscore.
756 • type defines which kind of storage is defined. See Supported Stor‐
758 ages.
759 • read_only defines whether the storage should be regarded as a
761 read-only storage. The value true means synchronization will discard
762 any changes made to the other side. The value false implies normal
763 2-way synchronization.
764 • Any further parameters are passed on to the storage class.
766 Supported Storages
768 CalDAV and CardDAV
769 NOTE:
770 Please also see Servers, as some servers may not work well.
771 caldav CalDAV.
773 [storage example_for_caldav]
775 type = "caldav"
776 #start_date = null
777 #end_date = null
778 #item_types = []
779 url = "..."
780 #username = ""
781 #password = ""
782 #verify = true
783 #auth = null
784 #useragent = "vdirsyncer/0.16.4"
785 #verify_fingerprint = null
786 #auth_cert = null
787 You can set a timerange to synchronize with the parameters
789 start_date and end_date. Inside those parameters, you can use
790 any Python expression to return a valid datetime.datetime ob‐
791 ject. For example, the following would synchronize the timerange
792 from one year in the past to one year in the future:
793 start_date = "datetime.now() - timedelta(days=365)"
795 end_date = "datetime.now() + timedelta(days=365)"
796 Either both or none have to be specified. The default is to syn‐
798 chronize everything.
799 You can set item_types to restrict the kind of items you want to
801 synchronize. For example, if you want to only synchronize events
802 (but don't download any tasks from the server), set item_types =
803 ["VEVENT"]. If you want to synchronize events and tasks, but
804 have some VJOURNAL items on the server you don't want to syn‐
805 chronize, use item_types = ["VEVENT", "VTODO"].
806 Parameters
808 • start_date -- Start date of timerange to show, default
810 -inf.
811 • end_date -- End date of timerange to show, default
813 +inf.
814 • item_types -- Kind of items to show. The default, the
816 empty list, is to show all. This depends on particular
817 features on the server, the results are not validated.
818 • url -- Base URL or an URL to a calendar.
820 • username -- Username for authentication.
822 • password -- Password for authentication.
824 • verify -- Verify SSL certificate, default True. This
826 can also be a local path to a self-signed SSL certifi‐
827 cate. See SSL and certificate validation for more in‐
828 formation.
829 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
831 of the expected server certificate. See SSL and cer‐
832 tificate validation for more information.
833 • auth -- Optional. Either basic, digest or guess. The
835 default is preemptive Basic auth, sending credentials
836 even if server didn't request them. This saves from an
837 additional roundtrip per request. Consider setting
838 guess if this causes issues with your server.
839 • auth_cert -- Optional. Either a path to a certificate
841 with a client certificate and the key or a list of
842 paths to the files with them.
843 • useragent -- Default vdirsyncer.
845 carddav
847 CardDAV.
848 [storage example_for_carddav]
850 type = "carddav"
851 url = "..."
852 #username = ""
853 #password = ""
854 #verify = true
855 #auth = null
856 #useragent = "vdirsyncer/0.16.4"
857 #verify_fingerprint = null
858 #auth_cert = null
859 Parameters
861 • url -- Base URL or an URL to an addressbook.
863 • username -- Username for authentication.
865 • password -- Password for authentication.
867 • verify -- Verify SSL certificate, default True. This
869 can also be a local path to a self-signed SSL certifi‐
870 cate. See SSL and certificate validation for more in‐
871 formation.
872 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
874 of the expected server certificate. See SSL and cer‐
875 tificate validation for more information.
876 • auth -- Optional. Either basic, digest or guess. The
878 default is preemptive Basic auth, sending credentials
879 even if server didn't request them. This saves from an
880 additional roundtrip per request. Consider setting
881 guess if this causes issues with your server.
882 • auth_cert -- Optional. Either a path to a certificate
884 with a client certificate and the key or a list of
885 paths to the files with them.
886 • useragent -- Default vdirsyncer.
888 Google
890 Vdirsyncer supports synchronization with Google calendars with the re‐
891 striction that VTODO files are rejected by the server.
892 Synchronization with Google contacts is less reliable due to negligence
894 of Google's CardDAV API. Google's CardDAV implementation is allegedly a
895 disaster in terms of data safety. See this blog post for the details.
896 Always back up your data.
897 At first run you will be asked to authorize application for Google ac‐
899 count access.
900 To use this storage type, you need to install some additional dependen‐
902 cies:
903 pip install vdirsyncer[google]
905 Furthermore you need to register vdirsyncer as an application yourself
907 to obtain client_id and client_secret, as it is against Google's Terms
908 of Service to hardcode those into opensource software [googleterms]:
909 1. Go to the Google API Manager and create a new project under any
911 name.
912 2. Within that project, enable the "CalDAV" and "CardDAV" APIs (not the
914 Calendar and Contacts APIs, those are different and won't work).
915 There should be a searchbox where you can just enter those terms.
916 3. In the sidebar, select "Credentials" and create a new "OAuth Client
918 ID". The application type is "Other".
919 You'll be prompted to create a OAuth consent screen first. Fill out
921 that form however you like.
922 4. Finally you should have a Client ID and a Client secret. Provide
924 these in your storage config.
925 The token_file parameter should be a filepath where vdirsyncer can
927 later store authentication-related data. You do not need to create the
928 file itself or write anything to it.
929 [googleterms]
931 See ToS, section "Confidential Matters".
932 NOTE:
934 You need to configure which calendars Google should offer vdirsyncer
935 using a rather hidden settings page.
936 google_calendar
938 Google calendar.
939 [storage example_for_google_calendar]
941 type = "google_calendar"
942 token_file = "..."
943 client_id = "..."
944 client_secret = "..."
945 #start_date = null
946 #end_date = null
947 #item_types = []
948 Please refer to caldav regarding the item_types and timerange
950 parameters.
951 Parameters
953 • token_file -- A filepath where access tokens are
955 stored.
956 • client_id/client_secret -- OAuth credentials, obtained
958 from the Google API Manager.
959 google_contacts
961 Google contacts.
962 [storage example_for_google_contacts]
964 type = "google_contacts"
965 token_file = "..."
966 client_id = "..."
967 client_secret = "..."
968 Parameters
970 • token_file -- A filepath where access tokens are
972 stored.
973 • client_id/client_secret -- OAuth credentials, obtained
975 from the Google API Manager.
976 EteSync
978 EteSync is a new cloud provider for end to end encrypted contacts and
979 calendar storage. Vdirsyncer contains experimental support for it.
980 To use it, you need to install some optional dependencies:
982 pip install vdirsyncer[etesync]
984 On first usage you will be prompted for the service password and the
986 encryption password. Neither are stored.
987 etesync_contacts
989 Contacts for etesync.
990 [storage example_for_etesync_contacts]
992 email = ...
993 secrets_dir = ...
994 #server_path = ...
995 #db_path = ...
996 Parameters
998 • email -- The email address of your account.
1000 • secrets_dir -- A directory where vdirsyncer can store
1002 the encryption key and authentication token.
1003 • server_url -- Optional. URL to the root of your custom
1005 server.
1006 • db_path -- Optional. Use a different path for the data‐
1008 base.
1009 etesync_calendars
1011 Calendars for etesync.
1012 [storage example_for_etesync_calendars]
1014 email = ...
1015 secrets_dir = ...
1016 #server_path = ...
1017 #db_path = ...
1018 Parameters
1020 • email -- The email address of your account.
1022 • secrets_dir -- A directory where vdirsyncer can store
1024 the encryption key and authentication token.
1025 • server_url -- Optional. URL to the root of your custom
1027 server.
1028 • db_path -- Optional. Use a different path for the data‐
1030 base.
1031 Local
1033 filesystem
1034 Saves each item in its own file, given a directory.
1035 [storage example_for_filesystem]
1037 type = "filesystem"
1038 path = "..."
1039 fileext = "..."
1040 #encoding = "utf-8"
1041 #post_hook = null
1042 #fileignoreext = ".tmp"
1043 Can be used with khal. See The Vdir Storage Format for a more
1045 formal description of the format.
1046 Directories with a leading dot are ignored to make usage of e.g.
1048 version control easier.
1049 Parameters
1051 • path -- Absolute path to a vdir/collection. If this is
1053 used in combination with the collections parameter in a
1054 pair-section, this should point to a directory of vdirs
1055 instead.
1056 • fileext -- The file extension to use (e.g. .txt). Con‐
1058 tained in the href, so if you change the file extension
1059 after a sync, this will trigger a re-download of every‐
1060 thing (but should not cause data-loss of any kind). To
1061 be compatible with the vset format you have to either
1062 use .vcf or .ics. Note that metasync won't work if you
1063 use an empty string here.
1064 • encoding -- File encoding for items, both content and
1066 filename.
1067 • post_hook -- A command to call for each item creation
1069 and modification. The command will be called with the
1070 path of the new/updated file.
1071 • fileeignoreext -- The file extention to ignore. It is
1073 only useful if fileext is set to the empty string. The
1074 default is .tmp.
1075 singlefile
1077 Save data in single local .vcf or .ics file.
1078 The storage basically guesses how items should be joined in the
1080 file.
1081 New in version 0.1.6.
1083 NOTE:
1086 This storage is very slow, and that is unlikely to change.
1087 You should consider using filesystem if it fits your usecase.
1088 Parameters
1090 • path -- The filepath to the file to be written to. If
1092 collections are used, this should contain %s as a
1093 placeholder for the collection name.
1094 • encoding -- Which encoding the file should use. De‐
1096 faults to UTF-8.
1097 Example for syncing with caldav:
1099 [pair my_calendar]
1101 a = my_calendar_local
1102 b = my_calendar_remote
1103 collections = ["from a", "from b"]
1104 [storage my_calendar_local]
1106 type = "singlefile"
1107 path = ~/.calendars/%s.ics
1108 [storage my_calendar_remote]
1110 type = "caldav"
1111 url = https://caldav.example.org/
1112 #username =
1113 #password =
1114 Example for syncing with caldav using a null collection:
1116 [pair my_calendar]
1118 a = my_calendar_local
1119 b = my_calendar_remote
1120 [storage my_calendar_local]
1122 type = "singlefile"
1123 path = ~/my_calendar.ics
1124 [storage my_calendar_remote]
1126 type = "caldav"
1127 url = https://caldav.example.org/username/my_calendar/
1128 #username =
1129 #password =
1130 Read-only storages
1132 These storages don't support writing of their items, consequently
1133 read_only is set to true by default. Changing read_only to false on
1134 them leads to an error.
1135 http Use a simple .ics file (or similar) from the web. web‐
1137 cal://-calendars are supposed to be used with this, but you have
1138 to replace webcal:// with http://, or better, https://.
1139 [pair holidays]
1141 a = holidays_local
1142 b = holidays_remote
1143 collections = null
1144 [storage holidays_local]
1146 type = "filesystem"
1147 path = ~/.config/vdir/calendars/holidays/
1148 fileext = .ics
1149 [storage holidays_remote]
1151 type = "http"
1152 url = https://example.com/holidays_from_hicksville.ics
1153 Too many WebCAL providers generate UIDs of all VEVENT-components
1155 on-the-fly, i.e. all UIDs change every time the calendar is
1156 downloaded. This leads many synchronization programs to believe
1157 that all events have been deleted and new ones created, and ac‐
1158 cordingly causes a lot of unnecessary uploads and deletions on
1159 the other side. Vdirsyncer completely ignores UIDs coming from
1160 http and will replace them with a hash of the normalized item
1161 content.
1162 Parameters
1164 • url -- URL to the .ics file.
1166 • username -- Username for authentication.
1168 • password -- Password for authentication.
1170 • verify -- Verify SSL certificate, default True. This
1172 can also be a local path to a self-signed SSL certifi‐
1173 cate. See SSL and certificate validation for more in‐
1174 formation.
1175 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
1177 of the expected server certificate. See SSL and cer‐
1178 tificate validation for more information.
1179 • auth -- Optional. Either basic, digest or guess. The
1181 default is preemptive Basic auth, sending credentials
1182 even if server didn't request them. This saves from an
1183 additional roundtrip per request. Consider setting
1184 guess if this causes issues with your server.
1185 • auth_cert -- Optional. Either a path to a certificate
1187 with a client certificate and the key or a list of
1188 paths to the files with them.
1189 • useragent -- Default vdirsyncer.
1191
1193 The following section contains tutorials not explicitly about any par‐
1194 ticular core function of vdirsyncer. They usually show how to integrate
1195 vdirsyncer with third-party software. Because of that, it may be that
1196 the information regarding that other software only applies to specific
1197 versions of them.
1198 NOTE:
1200 Please contribute your own tutorials too! Pages are often only
1201 stubs and are lacking full examples.
1202 Client applications
1204 Vdirsyncer with Claws Mail
1205 First of all, Claws-Mail only supports read-only functions for vCards.
1206 It can only read contacts, but there's no editor.
1207 Preparation
1209 We need to install vdirsyncer, for that look here. Then we need to
1210 create some folders:
1211 mkdir ~/.vdirsyncer
1213 mkdir ~/.contacts
1214 Configuration
1216 Now we create the configuration for vdirsyncer. Open ~/.vdirsyncer/con‐
1217 fig with a text editor. The config should look like this:
1218 [general]
1220 status_path = "~/.vdirsyncer/status/"
1221 [storage local]
1223 type = "singlefile"
1224 path = "~/.contacts/%s.vcf"
1225 [storage online]
1227 type = "carddav"
1228 url = "CARDDAV_LINK"
1229 username = "USERNAME"
1230 password = "PASSWORD"
1231 read_only = true
1232 [pair contacts]
1234 a = "local"
1235 b = "online"
1236 collections = ["from a", "from b"]
1237 conflict_resolution = "b wins"
1238 • In the general section, we define the status folder path, for discov‐
1240 ered collections and generally stuff that needs to persist between
1241 syncs.
1242 • In the local section we define that all contacts should be sync in a
1244 single file and the path for the contacts.
1245 • In the online section you must change the url, username and password
1247 to your setup. We also set the storage to read-only such that no
1248 changes get synchronized back. Claws-Mail should not be able to do
1249 any changes anyway, but this is one extra safety step in case files
1250 get corrupted or vdirsyncer behaves erratically. You can leave that
1251 part out if you want to be able to edit those files locally.
1252 • In the last section we configure that online contacts win in a con‐
1254 flict situation. Configure this part however you like. A correct
1255 value depends on which side is most likely to be up-to-date.
1256 Sync
1258 Now we discover and sync our contacts:
1259 vdirsyncer discover contacts
1261 vdirsyncer sync contacts
1262 Claws Mail
1264 Open Claws-Mail. Go to Tools => Addressbook.
1265 Click on Addressbook => New vCard. Choose a name for the book.
1267 Then search for the for the vCard in the folder ~/.contacts/. Click ok,
1269 and you we will see your contacts.
1270 NOTE:
1272 Claws-Mail shows only contacts that have a mail address.
1273 Crontab
1275 On the end we create a crontab, so that vdirsyncer syncs automatically
1276 every 30 minutes our contacts:
1277 crontab -e
1279 On the end of that file enter this line:
1281 */30 * * * * /usr/local/bin/vdirsyncer sync > /dev/null
1283 And you're done!
1285 Running as a systemd.timer
1287 vdirsyncer includes unit files to run at an interval (by default every
1288 15±5 minutes).
1289 NOTE:
1291 These are not installed when installing via pip, only via distribu‐
1292 tion packages. If you installed via pip, or your distribution
1293 doesn't ship systemd unit files, you'll need to download
1294 vdirsyncer.service and vdirsyncer.timer into either /etc/sys‐
1295 temd/user/ or ~/.local/share/systemd/user.
1296 Activation
1298 To activate the timer, just run systemctl --user enable
1299 vdirsyncer.timer. To see logs of previous runs, use journalctl --user
1300 -u vdirsyncer.
1301 Configuration
1303 It's quite possible that the default "every fifteen minutes" interval
1304 isn't to your liking. No default will suit everybody, but this is con‐
1305 figurable by simply running:
1306 systemctl --user edit vdirsyncer.timer
1308 This will open a blank editor, where you can override the timer by in‐
1310 cluding:
1311 OnBootSec=5m # This is how long after boot the first run takes place.
1313 OnUnitActiveSec=15m # This is how often subsequent runs take place.
1314 Todoman
1316 The iCalendar format also supports saving tasks in form of VTODO-en‐
1317 tries, with the same file extension as normal events: .ics. Many CalDAV
1318 servers support synchronizing tasks, vdirsyncer does too.
1319 todoman is a CLI task manager supporting vdir. Its interface is similar
1321 to the ones of Taskwarrior or the todo.txt CLI app. You can use
1322 filesystem with it.
1323 Setting up vdirsyncer
1325 For this tutorial we will use NextCloud.
1326 Assuming a config like this:
1328 [general]
1330 status_path = "~/.vdirsyncer/status/"
1331 [pair calendars]
1333 conflict_resolution = "b wins"
1334 a = "calendars_local"
1335 b = "calendars_dav"
1336 collections = ["from b"]
1337 metadata = ["color", "displayname"]
1338 [storage calendars_local]
1340 type = "filesystem"
1341 path = "~/.calendars/"
1342 fileext = ".ics"
1343 [storage calendars_dav]
1345 type = "caldav"
1346 url = "https://nextcloud.example.net/"
1347 username = "..."
1348 password = "..."
1349 vdirsyncer sync will then synchronize the calendars of your NextCloud
1351 instance to subfolders of ~/.calendar/.
1352 Setting up todoman
1354 Write this to ~/.config/todoman/todoman.conf:
1355 [main]
1357 path = ~/.calendars/*
1358 The glob pattern in path will match all subfolders in ~/.calendars/,
1360 which is exactly the tasklists we want. Now you can use todoman as de‐
1361 scribed in its documentation and run vdirsyncer sync to synchronize the
1362 changes to NextCloud.
1363 Other clients
1365 The following client applications also synchronize over CalDAV:
1366 • The Tasks-app found on iOS
1368 • OpenTasks for Android
1370 • The Tasks-app for NextCloud's web UI
1372 Further applications, with missing pages:
1374 • khal, a CLI calendar application supporting vdir. You can use
1376 filesystem with it.
1377 • Many graphical calendar apps such as dayplanner, Orage or rainlendar
1379 save a calendar in a single .ics file. You can use singlefile with
1380 those.
1381 • khard, a commandline addressbook supporting vdir. You can use
1383 filesystem with it.
1384 • contactquery.c, a small program explicitly written for querying vdirs
1386 from mutt.
1387 • mates, a commandline addressbook supporting vdir.
1389 • vdirel, access vdir contacts from Emacs.
1391 Servers
1393 Baikal
1394 Vdirsyncer is continuously tested against the latest version of Baikal.
1395 • Baikal up to 0.2.7 also uses an old version of SabreDAV, with the
1397 same issue as ownCloud, see issue #160. This issue is fixed in later
1398 versions.
1399 DavMail (Exchange, Outlook)
1401 DavMail is a proxy program that allows you to use Card- and CalDAV
1402 clients with Outlook. That allows you to use vdirsyncer with Outlook.
1403 In practice your success with DavMail may wildly vary. Depending on
1405 your Exchange server you might get confronted with weird errors of all
1406 sorts (including data-loss).
1407 Make absolutely sure you use the latest DavMail:
1409 [storage outlook]
1411 type = "caldav"
1412 url = "http://localhost:1080/users/user@example.com/calendar/"
1413 username = "user@example.com"
1414 password = "..."
1415 • Older versions of DavMail handle URLs case-insensitively. See issue
1417 #144.
1418 • DavMail is handling malformed data on the Exchange server very
1420 poorly. In such cases the Calendar Checking Tool for Outlook might
1421 help.
1422 • In some cases, you may see errors about duplicate events. It may look
1424 something like this:
1425 error: my_calendar/calendar: Storage "my_calendar_remote/calendar" contains multiple items with the same UID or even content. Vdirsyncer will now abort the synchronization of this collection, because the fix for this is not clear; It could be the result of a badly behaving server. You can try running:
1427 error:
1428 error: vdirsyncer repair my_calendar_remote/calendar
1429 error:
1430 error: But make sure to have a backup of your data in some form. The offending hrefs are:
1431 [...]
1432 In order to fix this, you can try the
1434 Remove-DuplicateAppointments.ps1 PowerShell script that Microsoft has
1435 come up with in order to remove duplicates.
1436 FastMail
1438 Vdirsyncer is continuously tested against FastMail, thanks to them for
1439 providing a free account for this purpose. There are no known issues
1440 with it. FastMail's support pages provide the settings to use:
1441 [storage cal]
1443 type = "caldav"
1444 url = "https://caldav.fastmail.com/"
1445 username = "..."
1446 password = "..."
1447 [storage card]
1449 type = "carddav"
1450 url = "https://carddav.fastmail.com/"
1451 username = "..."
1452 password = "..."
1453 Google
1455 Using vdirsyncer with Google Calendar is possible as of 0.10, but it is
1456 not tested frequently. You can use google_contacts and google_calendar.
1457 For more information see issue #202 and issue #8.
1459 iCloud
1461 Vdirsyncer is regularly tested against iCloud.
1462 [storage cal]
1464 type = "caldav"
1465 url = "https://caldav.icloud.com/"
1466 username = "..."
1467 password = "..."
1468 [storage card]
1470 type = "carddav"
1471 url = "https://contacts.icloud.com/"
1472 username = "..."
1473 password = "..."
1474 Problems:
1476 • Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem
1478 to be a way to do two-factor auth over the DAV APIs) You'll need to
1479 use app-specific passwords instead.
1480 • iCloud has a few special requirements when creating collections. In
1482 principle vdirsyncer can do it, but it is recommended to create them
1483 from an Apple client (or the iCloud web interface).
1484 • iCloud requires a minimum length of collection names.
1486 • Calendars created by vdirsyncer cannot be used as tasklists.
1488 nextCloud
1490 Vdirsyncer is continuously tested against the latest version of
1491 nextCloud:
1492 [storage cal]
1494 type = "caldav"
1495 url = "https://nextcloud.example.com/"
1496 username = "..."
1497 password = "..."
1498 [storage card]
1500 type = "carddav"
1501 url = "https://nextcloud.example.com/"
1502 • WebCAL-subscriptions can't be discovered by vdirsyncer. See this rel‐
1504 evant issue.
1505 ownCloud
1507 Vdirsyncer is continuously tested against the latest version of
1508 ownCloud:
1509 [storage cal]
1511 type = "caldav"
1512 url = "https://example.com/remote.php/dav/"
1513 username = ...
1514 password = ...
1515 [storage card]
1517 type = "carddav"
1518 url = "https://example.com/remote.php/dav/"
1519 username = ...
1520 password = ...
1521 • Versions older than 7.0.0: ownCloud uses SabreDAV, which had problems
1523 detecting collisions and race-conditions. The problems were reported
1524 and are fixed in SabreDAV's repo, and the corresponding fix is also
1525 in ownCloud since 7.0.0. See issue #16 for more information.
1526 Radicale
1528 Radicale is a very lightweight server, however, it intentionally
1529 doesn't implement the CalDAV and CardDAV standards completely, which
1530 might lead to issues even with very well-written clients. Apart from
1531 its non-conformity with standards, there are multiple other problems
1532 with its code quality and the way it is maintained. Consider using e.g.
1533 Xandikos instead.
1534 That said, vdirsyncer is continuously tested against the git version
1536 and the latest PyPI release of Radicale.
1537 • Vdirsyncer can't create collections on Radicale.
1539 • Radicale doesn't support time ranges in the calendar-query of CalDAV,
1541 so setting start_date and end_date for caldav will have no or unpre‐
1542 dicted consequences.
1543 • Versions of Radicale older than 0.9b1 choke on RFC-conform queries
1545 for all items of a collection.
1546 You have to set item_types = ["VTODO", "VEVENT"] in caldav for
1548 vdirsyncer to work with those versions.
1549 Xandikos
1551 Xandikos is a lightweight, yet complete CalDAV and CardDAV server,
1552 backed by git. Vdirsyncer is continuously tested against its latest
1553 version.
1554 After running ./bin/xandikos --defaults -d $HOME/dav, you should be
1556 able to point vdirsyncer against the root of Xandikos like this:
1557 [storage cal]
1559 type = "caldav"
1560 url = "https://xandikos.example.com/"
1561 username = "..."
1562 password = "..."
1563 [storage card]
1565 type = "carddav"
1566 url = "https://xandikos.example.com/"
1567 username = "..."
1568 password = "..."
1569
1571 For any unanswered questions or problems, see Support and Contact.
1572 Requests-related ImportErrors
1574 ImportError: No module named packages.urllib3.poolmanager
1575 ImportError: cannot import name iter_field_objects
1577 Debian and nowadays even other distros make modifications to the re‐
1579 quests package that don't play well with packages assuming a normal re‐
1580 quests. This is due to stubbornness on both sides.
1581 See issue #82 and issue #140 for past discussions. You have one option
1583 to work around this, that is, to install vdirsyncer in a virtualenv,
1584 see Manual installation.
1585
1587 NOTE:
1588 • Please read Support and Contact for questions and support re‐
1590 quests.
1591 • All participants must follow the pimutils Code of Conduct.
1593 The issue tracker
1595 We use GitHub issues for organizing bug reports and feature requests.
1596 The following labels are of interest:
1598 • "Planning" is for issues that are still undecided, but where at least
1600 some discussion exists.
1601 • "Blocked" is for issues that can't be worked on at the moment because
1603 some other unsolved problem exists. This problem may be a bug in some
1604 software dependency, for instance.
1605 • "Ready" contains issues that are ready to work on.
1607 If you just want to get started with contributing, the "ready" issues
1609 are an option. Issues that are still in "Planning" are also an option,
1610 but require more upfront thinking and may turn out to be impossible to
1611 solve, or at least harder than anticipated. On the flip side those tend
1612 to be the more interesting issues as well, depending on how one looks
1613 at it.
1614 All of those labels are also available as a kanban board on waffle.io.
1616 It is really just an alternative overview over all issues, but might be
1617 easier to comprehend.
1618 Feel free to contact me or comment on the relevant issues for further
1620 information.
1621 Reporting bugs
1623 • Make sure your problem isn't already listed in Known Problems.
1624 • Make sure you have the absolutely latest version of vdirsyncer. For
1626 users of some Linux distributions such as Debian or Fedora this may
1627 not be the version that your distro offers. In those cases please
1628 file a bug against the distro package, not against upstream
1629 vdirsyncer.
1630 • Use --verbosity=DEBUG when including output from vdirsyncer.
1632 Suggesting features
1634 If you're suggesting a feature, keep in mind that vdirsyncer tries not
1635 to be a full calendar or contacts client, but rather just the piece of
1636 software that synchronizes all the data. Take a look at the documenta‐
1637 tion for software working with vdirsyncer.
1638 Submitting patches, pull requests
1640 • Discuss everything in the issue tracker first (or contact me somehow
1641 else) before implementing it.
1642 • Make sure the tests pass. See below for running them.
1644 • But not because you wrote too few tests.
1646 • Add yourself to AUTHORS.rst, and add a note to CHANGELOG.rst too.
1648 Running tests, how to set up your development environment
1650 For many patches, it might suffice to just let CI run the tests. How‐
1651 ever, CI is slow, so you might want to run them locally too. For this,
1652 set up a virtualenv and run this inside of it:
1653 # install:
1655 # - vdirsyncer from the repo into the virtualenv
1656 # - stylecheckers (flake8) and code formatters (autopep8)
1657 make install-dev
1658 # Install git commit hook for some extra linting and checking
1660 pre-commit install
1661 # Install development dependencies
1663 make install-dev
1664 Then you can run:
1666 make test # The normal testsuite
1668 make style # Stylechecker
1669 make docs # Build the HTML docs, output is at docs/_build/html/
1670 The Makefile has a lot of options that allow you to control which tests
1672 are run, and which servers are tested. Take a look at its code where
1673 they are all initialized and documented.
1674 To tests against a specific DAV server, use DAV_SERVER:
1676 make DAV_SERVER=xandikos test
1678 The server will be initialised in a docker container and terminated at
1680 the end of the test suite.
1681 If you have any questions, feel free to open issues about it.
1683 Structure of the testsuite
1685 Within tests/, there are three main folders:
1686 • system contains system- and also integration tests. A rough rule is:
1688 If the test is using temporary files, put it here.
1689 • unit, where each testcase tests a single class or function.
1691 • storage runs a generic storage testsuite against all storages.
1693 The reason for this separation is: We are planning to generate separate
1695 coverage reports for each of those testsuites. Ideally unit would gen‐
1696 erate palatable coverage of the entire codebase on its own, and the
1697 combination of system and storage as well.
1698
1700 This document describes a standard for storing calendars and contacts
1701 on a filesystem, with the main goal of being easy to implement.
1702 Vdirsyncer synchronizes to vdirs via filesystem. Each vdir (basically
1704 just a directory with some files in it) represents a calendar or ad‐
1705 dressbook.
1706 Basic Structure
1708 The main folder (root) contains an arbitrary number of subfolders (col‐
1709 lections), which contain only files (items). Synonyms for "collection"
1710 may be "addressbook" or "calendar".
1711 An item is:
1713 • A vCard file, in which case the file extension must be .vcf, or
1715 • An iCalendar file, in which case the file extension must be .ics.
1717 An item should contain a UID property as described by the vCard and
1719 iCalendar standards. If it contains more than one UID property, the
1720 values of those must not differ.
1721 The file must contain exactly one event, task or contact. In most cases
1723 this also implies only one VEVENT/VTODO/VCARD component per file, but
1724 e.g. recurrence exceptions would require multiple VEVENT components
1725 per event.
1726 The filename should have similar properties as the UID of the file con‐
1728 tent. However, there is no requirement for these two to be the same.
1729 Programs may choose to store additional metadata in that filename, how‐
1730 ever, at the same time they must not assume that the metadata they in‐
1731 cluded will be preserved by other programs.
1732 Metadata
1734 Any of the below metadata files may be absent. None of the files listed
1735 below have any file extensions.
1736 • A file called color inside the vdir indicates the vdir's color, a
1738 property that is only relevant in UI design.
1739 Its content is an ASCII-encoded hex-RGB value of the form #RRGGBB.
1741 For example, a file content of #FF0000 indicates that the vdir has a
1742 red (user-visible) color. No short forms or informal values such as
1743 red (as known from CSS, for example) are allowed. The prefixing #
1744 must be present.
1745 • A file called displayname contains a UTF-8 encoded label that may be
1747 used to represent the vdir in UIs.
1748 Writing to vdirs
1750 Creating and modifying items or metadata files should happen
1751 atomically.
1752 Writing to a temporary file on the same physical device, and then mov‐
1754 ing it to the appropriate location is usually a very effective solu‐
1755 tion. For this purpose, files with the extension .tmp may be created
1756 inside collections.
1757 When changing an item, the original filename must be used.
1759 Reading from vdirs
1761 • Any file ending with the .tmp or no file extension must not be
1762 treated as an item.
1763 • The ident part of the filename should not be parsed to improve the
1765 speed of item lookup.
1766 Considerations
1768 The primary reason this format was chosen is due to its compatibility
1769 with the CardDAV and CalDAV standards.
1770 Performance
1772 Currently, vdirs suffer from a rather major performance problem, one
1773 which current implementations try to mitigate by building up indices of
1774 the collections for faster search and lookup.
1775 The reason items' filenames don't contain any extra information is sim‐
1777 ple: The solutions presented induced duplication of data, where one du‐
1778 plicate might become out of date because of bad implementations. As it
1779 stands right now, an index format could be formalized separately
1780 though.
1781 vdirsyncer doesn't really have to bother about efficient item lookup,
1783 because its synchronization algorithm needs to fetch the whole list of
1784 items anyway. Detecting changes is easily implemented by checking the
1785 files' modification time.
1786
1788 Thank you very much for packaging vdirsyncer! The following guidelines
1789 should help you to avoid some common pitfalls.
1790 If you find yourself needing to patch anything, or going in a different
1792 direction, please open an issue so we can also address in a way that
1793 works for everyone. Otherwise we get bug reports for code or scenarios
1794 that don't exist in upstream vdirsycner.
1795 Obtaining the source code
1797 The main distribution channel is PyPI, and source tarballs can be ob‐
1798 tained there. We mirror the same package tarball and wheel as GitHub
1799 releases. Please do not confuse these with the auto-generated GitHub
1800 "Source Code" tarball. Those are missing some important metadata and
1801 your build will fail.
1802 We give each release a tag in the git repo. If you want to get notified
1804 of new releases, GitHub's feed is a good way.
1805 Tags will be signed by the maintainer who is doing the release (start‐
1807 ing with 0.16.8), and generation of the tarball and wheel is done by
1808 CI. Hence, only the tag itself is signed.
1809 Dependency versions
1811 As with most Python packages, setup.py denotes the dependencies of
1812 vdirsyncer. It also contains lower-bound versions of each dependency.
1813 Older versions will be rejected by the testsuite.
1814 Testing
1816 Everything testing-related goes through the Makefile in the root of the
1817 repository or PyPI package. Trying to e.g. run pytest directly will re‐
1818 quire a lot of environment variables to be set (for configuration) and
1819 you probably don't want to deal with that.
1820 You can install the all development dependencies with:
1822 make install-dev
1824 You probably don't want this since it will use pip to download the de‐
1826 pendencies. Alternatively you can find the testing dependencies in
1827 test-requirements.txt, again with lower-bound version requirements.
1828 You also have to have vdirsyncer fully installed at this point. Merely
1830 cd-ing into the tarball will not be sufficient.
1831 Running the tests happens with:
1833 make test
1835 Hypothesis will randomly generate test input. If you care about deter‐
1837 ministic tests, set the DETERMINISTIC_TESTS variable to "true":
1838 make DETERMINISTIC_TESTS=true test
1840 There are a lot of additional variables that allow you to test
1842 vdirsyncer against a particular server. Those variables are not "sta‐
1843 ble" and may change drastically between minor versions. Just don't use
1844 them, you are unlikely to find bugs that vdirsyncer's CI hasn't found.
1845 Documentation
1847 Using Sphinx you can generate the documentation you're reading right
1848 now in a variety of formats, such as HTML, PDF, or even as a manpage.
1849 That said, I only take care of the HTML docs' formatting.
1850 You can find a list of dependencies in docs-requirements.txt. Again,
1852 you can install those using pip with:
1853 make install-docs
1855 Then change into the docs/ directory and build whatever format you want
1857 using the Makefile in there (run make for the formats you can build).
1858 Contrib files
1860 Reference systemd.service and systemd.timer unit files are provided. It
1861 is recommended to install this if your distribution is systemd-based.
1862
1864 • The #pimutils IRC channel on Libera.Chat might be active, depending
1865 on your timezone. Use it for support and general (including
1866 off-topic) discussion.
1867 • Open a GitHub issue for concrete bug reports and feature requests.
1869 • Lastly, you can also contact the author directly. Do this for secu‐
1871 rity issues. If that doesn't work out (i.e. if I don't respond within
1872 one week), use contact@pimutils.org.
1873
1875 This changelog only contains information that might be useful to end
1876 users and package maintainers. For further info, see the git commit
1877 log.
1878 Package maintainers and users who have to manually update their instal‐
1880 lation may want to subscribe to GitHub's tag feed.
1881 Version 0.18.0
1883 Note: Version 0.17 has some alpha releases but ultimately was never fi‐
1884 nalised. 0.18 actually continues where 0.16 left off.
1885 • Support for Python 3.5 and 3.6 has been dropped. This release mostly
1887 focuses on keeping vdirsyncer compatible with newer environments.
1888 • click 8 and click-threading 0.5.0 are now required.
1890 • For those using pipsi, we now recommend using pipx, it's successor.
1892 • Python 3.9 is now supported.
1894 • Our Debian/Ubuntu build scripts have been updated. New versions
1896 should be pushed to those repositories soon.
1897 Version 0.16.8
1899 released 09 June 2020
1900 • Support Python 3.7 and 3.8.
1902 This release is functionally identical to 0.16.7. It's been tested
1904 with recent Python versions, and has been marked as supporting them. It
1905 will also be the final release supporting Python 3.5 and 3.6.
1906 Version 0.16.7
1908 released on 19 July 2018
1909 • Fixes for Python 3.7
1911 Version 0.16.6
1913 released on 13 June 2018
1914 • Packagers: Documentation building no longer needs a working installa‐
1916 tion of vdirsyncer.
1917 Version 0.16.5
1919 released on 13 June 2018
1920 • Packagers: click-log 0.3 is required.
1922 • All output will now happen on stderr (because of the upgrade of
1924 click-log).
1925 Version 0.16.4
1927 released on 05 February 2018
1928 • Fix tests for new Hypothesis version. (Literally no other change in‐
1930 cluded)
1931 Version 0.16.3
1933 released on 03 October 2017
1934 • First version with custom Debian and Ubuntu packages. See issue #663.
1936 • Remove invalid ASCII control characters from server responses. See
1938 issue #626.
1939 • packagers: Python 3.3 is no longer supported. See pull request #674.
1941 Version 0.16.2
1943 released on 24 August 2017
1944 • Fix crash when using daterange or item_type filters in
1946 google_calendar, see issue #657.
1947 • Packagers: Fixes for new version 0.2.0 of click-log. The version re‐
1949 quirements for the dependency click-log changed.
1950 Version 0.16.1
1952 released on 8 August 2017
1953 • Removed remoteStorage support, see issue #647.
1955 • Fixed test failures caused by latest requests version, see issue
1957 #660.
1958 Version 0.16.0
1960 released on 2 June 2017
1961 • Strip METHOD:PUBLISH added by some calendar providers, see issue
1963 #502.
1964 • Fix crash of Google storages when saving token file.
1966 • Make DAV discovery more RFC-conformant, see pull request #585.
1968 • Vdirsyncer is now tested against Xandikos, see pull request #601.
1970 • Subfolders with a leading dot are now ignored during discover for
1972 filesystem storage. This makes it easier to combine it with version
1973 control.
1974 • Statuses are now stored in a sqlite database. Old data is automati‐
1976 cally migrated. Users with really large datasets should encounter
1977 performance improvements. This means that sqlite3 is now a dependency
1978 of vdirsyncer.
1979 • Vdirsyncer is now licensed under the 3-clause BSD license, see issue
1981 #610.
1982 • Vdirsyncer now includes experimental support for EteSync, see pull
1984 request #614.
1985 • Vdirsyncer now uses more filesystem metadata for determining whether
1987 an item changed. You will notice a possibly heavy CPU/IO spike on the
1988 first sync after upgrading.
1989 • Packagers: Reference systemd.service and systemd.timer unit files are
1991 provided. It is recommended to install these as documentation if your
1992 distribution is systemd-based.
1993 Version 0.15.0
1995 released on 28 February 2017
1996 • Deprecated syntax for configuration values is now completely re‐
1998 jected. All values now have to be valid JSON.
1999 • A few UX improvements for Google storages, see issue #549 and issue
2001 #552.
2002 • Fix collection discovery for google_contacts, see issue #564.
2004 • iCloud is now tested on Travis, see issue #567.
2006 Version 0.14.1
2008 released on 05 January 2017
2009 • vdirsyncer repair no longer changes "unsafe" UIDs by default, an ex‐
2011 tra option has to be specified. See issue #527.
2012 • A lot of important documentation updates.
2014 Version 0.14.0
2016 released on 26 October 2016
2017 • vdirsyncer sync now continues other uploads if one upload failed.
2019 The exit code in such situations is still non-zero.
2020 • Add partial_sync option to pair section. See the config docs.
2022 • Vdirsyncer will now warn if there's a string without quotes in your
2024 config. Please file issues if you find documentation that uses un‐
2025 quoted strings.
2026 • Fix an issue that would break khal's config setup wizard.
2028 Version 0.13.1
2030 released on 30 September 2016
2031 • Fix a bug that would completely break collection discovery.
2033 Version 0.13.0
2035 released on 29 September 2016
2036 • Python 2 is no longer supported at all. See issue #219.
2038 • Config sections are now checked for duplicate names. This also means
2040 that you cannot have a storage section [storage foo] and a pair [pair
2041 foo] in your config, they have to have different names. This is done
2042 such that console output is always unambiguous. See issue #459.
2043 • Custom commands can now be used for conflict resolution during sync.
2045 See issue #127.
2046 • http now completely ignores UIDs. This avoids a lot of unnecessary
2048 down- and uploads.
2049 Version 0.12.1
2051 released on 20 August 2016
2052 • Fix a crash for Google and DAV storages. See pull request #492.
2054 • Fix an URL-encoding problem with DavMail. See issue #491.
2056 Version 0.12
2058 released on 19 August 2016
2059 • singlefile now supports collections. See pull request #488.
2061 Version 0.11.3
2063 released on 29 July 2016
2064 • Default value of auth parameter was changed from guess to basic to
2066 resolve issues with the Apple Calendar Server (issue #457) and im‐
2067 prove performance. See issue #461.
2068 • Packagers: The click-threading requirement is now >=0.2. It was in‐
2070 correct before. See issue #478.
2071 • Fix a bug in the DAV XML parsing code that would make vdirsyncer
2073 crash on certain input. See issue #480.
2074 • Redirect chains should now be properly handled when resolving
2076 well-known URLs. See pull request #481.
2077 Version 0.11.2
2079 released on 15 June 2016
2080 • Fix typo that would break tests.
2082 Version 0.11.1
2084 released on 15 June 2016
2085 • Fix a bug in collection validation.
2087 • Fix a cosmetic bug in debug output.
2089 • Various documentation improvements.
2091 Version 0.11.0
2093 released on 19 May 2016
2094 • Discovery is no longer automatically done when running vdirsyncer
2096 sync. vdirsyncer discover now has to be explicitly called.
2097 • Add a .plist example for Mac OS X.
2099 • Usage under Python 2 now requires a special config parameter to be
2101 set.
2102 • Various deprecated configuration parameters do no longer have spe‐
2104 cialized errormessages. The generic error message for unknown parame‐
2105 ters is shown.
2106 • Vdirsyncer no longer warns that the passwordeval parameter has been
2108 renamed to password_command.
2109 • The keyring fetching strategy has been dropped some versions ago,
2111 but the specialized error message has been dropped.
2112 • An old status format from version 0.4 is no longer supported. If
2114 you're experiencing problems, just delete your status folder.
2115 Version 0.10.0
2117 released on 23 April 2016
2118 • New storage types google_calendar and google_contacts have been
2120 added.
2121 • New global command line option --config, to specify an alternative
2123 config file. See issue #409.
2124 • The collections parameter can now be used to synchronize differ‐
2126 ently-named collections with each other.
2127 • Packagers: The lxml dependency has been dropped.
2129 • XML parsing is now a lot stricter. Malfunctioning servers that used
2131 to work with vdirsyncer may stop working.
2132 Version 0.9.3
2134 released on 22 March 2016
2135 • singlefile and http now handle recurring events properly.
2137 • Fix a typo in the packaging guidelines.
2139 • Moved to pimutils organization on GitHub. Old links should redirect,
2141 but be aware of client software that doesn't properly handle redi‐
2142 rects.
2143 Version 0.9.2
2145 released on 13 March 2016
2146 • Fixed testsuite for environments that don't have any web browser in‐
2148 stalled. See pull request #384.
2149 Version 0.9.1
2151 released on 13 March 2016
2152 • Removed leftover debug print statement in vdirsyncer discover, see
2154 commit 3d856749f37639821b148238ef35f1acba82db36.
2155 • metasync will now strip whitespace from the start and the end of the
2157 values. See issue #358.
2158 • New Packaging Guidelines have been added to the documentation.
2160 Version 0.9.0
2162 released on 15 February 2016
2163 • The collections parameter is now required in pair configurations.
2165 Vdirsyncer will tell you what to do in its error message. See issue
2166 #328.
2167 Version 0.8.1
2169 released on 30 January 2016
2170 • Fix error messages when invalid parameter fetching strategy is used.
2172 This is important because users would receive awkward errors for us‐
2173 ing deprecated keyring fetching.
2174 Version 0.8.0
2176 released on 27 January 2016
2177 • Keyring support has been removed, which means that password.fetch =
2179 ["keyring", "example.com", "myuser"] doesn't work anymore.
2180 For existing setups: Use password.fetch = ["command", "keyring",
2182 "get", "example.com", "myuser"] instead, which is more generic. See
2183 the documentation for details.
2184 • Now emitting a warning when running under Python 2. See issue #219.
2186 Version 0.7.5
2188 released on 23 December 2015
2189 • Fixed a bug in remotestorage that would try to open a CLI browser for
2191 OAuth.
2192 • Fix a packaging bug that would prevent vdirsyncer from working with
2194 newer lxml versions.
2195 Version 0.7.4
2197 released on 22 December 2015
2198 • Improved error messages instead of faulty server behavior, see issue
2200 #290 and issue #300.
2201 • Safer shutdown of threadpool, avoid exceptions, see issue #291.
2203 • Fix a sync bug for read-only storages see commit
2205 ed22764921b2e5bf6a934cf14aa9c5fede804d8e.
2206 • Etag changes are no longer sufficient to trigger sync operations. An
2208 actual content change is also necessary. See issue #257.
2209 • remotestorage now automatically opens authentication dialogs in your
2211 configured GUI browser.
2212 • Packagers: lxml>=3.1 is now required (newer lower-bound version).
2214 Version 0.7.3
2216 released on 05 November 2015
2217 • Make remotestorage-dependencies actually optional.
2219 Version 0.7.2
2221 released on 05 November 2015
2222 • Un-break testsuite.
2224 Version 0.7.1
2226 released on 05 November 2015
2227 • Packagers: The setuptools extras keyring and remotestorage have been
2229 added. They're basically optional dependencies. See setup.py for more
2230 details.
2231 • Highly experimental remoteStorage support has been added. It may be
2233 completely overhauled or even removed in any version.
2234 • Removed mentions of old password_command in documentation.
2236 Version 0.7.0
2238 released on 27 October 2015
2239 • Packagers: New dependencies are click_threading, click_log and
2241 click>=5.0.
2242 • password_command is gone. Keyring support got completely overhauled.
2244 See Storing passwords.
2245 Version 0.6.0
2247 released on 06 August 2015
2248 • password_command invocations with non-zero exit code are now fatal
2250 (and will abort synchronization) instead of just producing a warning.
2251 • Vdirsyncer is now able to synchronize metadata of collections. Set
2253 metadata = ["displayname"] and run vdirsyncer metasync.
2254 • Packagers: Don't use the GitHub tarballs, but the PyPI ones.
2256 • Packagers: build.sh is gone, and Makefile is included in tarballs.
2258 See the content of Makefile on how to run tests post-packaging.
2259 • verify_fingerprint doesn't automatically disable verify anymore.
2261 Version 0.5.2
2263 released on 15 June 2015
2264 • Vdirsyncer now checks and corrects the permissions of status files.
2266 • Vdirsyncer is now more robust towards changing UIDs inside items.
2268 • Vdirsyncer is now handling unicode hrefs and UIDs correctly. Software
2270 that produces non-ASCII UIDs is broken, but apparently it exists.
2271 Version 0.5.1
2273 released on 29 May 2015
2274 • N.b.: The PyPI upload of 0.5.0 is completely broken.
2276 • Raise version of required requests-toolbelt to 0.4.0.
2278 • Command line should be a lot faster when no work is done, e.g. for
2280 help output.
2281 • Fix compatibility with iCloud again.
2283 • Use only one worker if debug mode is activated.
2285 • verify=false is now disallowed in vdirsyncer, please use verify_fin‐
2287 gerprint instead.
2288 • Fixed a bug where vdirsyncer's DAV storage was not using the config‐
2290 ured useragent for collection discovery.
2291 Version 0.4.4
2293 released on 12 March 2015
2294 • Support for client certificates via the new auth_cert parameter, see
2296 issue #182 and pull request #183.
2297 • The icalendar package is no longer required.
2299 • Several bugfixes related to collection creation.
2301 Version 0.4.3
2303 released on 20 February 2015
2304 • More performance improvements to singlefile-storage.
2306 • Add post_hook param to filesystem-storage.
2308 • Collection creation now also works with SabreDAV-based servers, such
2310 as Baikal or ownCloud.
2311 • Removed some workarounds for Radicale. Upgrading to the latest Radi‐
2313 cale will fix the issues.
2314 • Fixed issues with iCloud discovery.
2316 • Vdirsyncer now includes a simple repair command that seeks to fix
2318 some broken items.
2319 Version 0.4.2
2321 released on 30 January 2015
2322 • Vdirsyncer now respects redirects when uploading and updating items.
2324 This might fix issues with Zimbra.
2325 • Relative status_path values are now interpreted as relative to the
2327 configuration file's directory.
2328 • Fixed compatibility with custom SabreDAV servers. See issue #166.
2330 • Catch harmless threading exceptions that occur when shutting down
2332 vdirsyncer. See issue #167.
2333 • Vdirsyncer now depends on atomicwrites.
2335 • Massive performance improvements to singlefile-storage.
2337 • Items with extremely long UIDs should now be saved properly in
2339 filesystem-storage. See issue #173.
2340 Version 0.4.1
2342 released on 05 January 2015
2343 • All create arguments from all storages are gone. Vdirsyncer now asks
2345 if it should try to create collections.
2346 • The old config values True, False, on, off and None are now invalid.
2348 • UID conflicts are now properly handled instead of ignoring one item.
2350 Card- and CalDAV servers are already supposed to take care of those
2351 though.
2352 • Official Baikal support added.
2354 Version 0.4.0
2356 released on 31 December 2014
2357 • The passwordeval parameter has been renamed to password_command.
2359 • The old way of writing certain config values such as lists is now
2361 gone.
2362 • Collection discovery has been rewritten. Old configuration files
2364 should be compatible with it, but vdirsyncer now caches the results
2365 of the collection discovery. You have to run vdirsyncer discover if
2366 collections were added or removed on one side.
2367 • Pair and storage names are now restricted to certain characters.
2369 Vdirsyncer will issue a clear error message if your configuration
2370 file is invalid in that regard.
2371 • Vdirsyncer now supports the XDG-Basedir specification. If the
2373 VDIRSYNCER_CONFIG environment variable isn't set and the
2374 ~/.vdirsyncer/config file doesn't exist, it will look for the config‐
2375 uration file at $XDG_CONFIG_HOME/vdirsyncer/config.
2376 • Some improvements to CardDAV and CalDAV discovery, based on problems
2378 found with FastMail. Support for .well-known-URIs has been added.
2379 Version 0.3.4
2381 released on 8 December 2014
2382 • Some more bugfixes to config handling.
2384 Version 0.3.3
2386 released on 8 December 2014
2387 • Vdirsyncer now also works with iCloud. Particularly collection dis‐
2389 covery and etag handling were fixed.
2390 • Vdirsyncer now encodes Cal- and CardDAV requests differently. This
2392 hasn't been well-tested with servers like Zimbra or SoGo, but isn't
2393 expected to cause any problems.
2394 • Vdirsyncer is now more robust regarding invalid responses from CalDAV
2396 servers. This should help with future compatibility with Davmail/Out‐
2397 look.
2398 • Fix a bug when specifying item_types of caldav in the deprecated con‐
2400 fig format.
2401 • Fix a bug where vdirsyncer would ignore all but one character speci‐
2403 fied in unsafe_href_chars of caldav and carddav.
2404 Version 0.3.2
2406 released on 3 December 2014
2407 • The current config format has been deprecated, and support for it
2409 will be removed in version 0.4.0. Vdirsyncer warns about this now.
2410 Version 0.3.1
2412 released on 24 November 2014
2413 • Fixed a bug where vdirsyncer would delete items if they're deleted on
2415 side A but modified on side B. Instead vdirsyncer will now upload the
2416 new items to side A. See issue #128.
2417 • Synchronization continues with the remaining pairs if one pair
2419 crashes, see issue #121.
2420 • The processes config key is gone. There is now a --max-workers option
2422 on the CLI which has a similar purpose. See pull request #126.
2423 • The Read The Docs-theme is no longer required for building the docs.
2425 If it is not installed, the default theme will be used. See issue
2426 #134.
2427 Version 0.3.0
2429 released on 20 September 2014
2430 • Add verify_fingerprint parameter to http, caldav and carddav, see
2432 issue #99 and pull request #106.
2433 • Add passwordeval parameter to General Section, see issue #108 and
2435 pull request #117.
2436 • Emit warnings (instead of exceptions) about certain invalid responses
2438 from the server, see issue #113. This is apparently required for
2439 compatibility with Davmail.
2440 Version 0.2.5
2442 released on 27 August 2014
2443 • Don't ask for the password of one server more than once and fix mul‐
2445 tiple concurrency issues, see issue #101.
2446 • Better validation of DAV endpoints.
2448 Version 0.2.4
2450 released on 18 August 2014
2451 • Include workaround for collection discovery with latest version of
2453 Radicale.
2454 • Include metadata files such as the changelog or license in source
2456 distribution, see issue #97 and issue #98.
2457 Version 0.2.3
2459 released on 11 August 2014
2460 • Vdirsyncer now has a --version flag, see issue #92.
2462 • Fix a lot of bugs related to special characters in URLs, see issue
2464 #49.
2465 Version 0.2.2
2467 released on 04 August 2014
2468 • Remove a security check that caused problems with special characters
2470 in DAV URLs and certain servers. On top of that, the security check
2471 was nonsensical. See issue #87 and issue #91.
2472 • Change some errors to warnings, see issue #88.
2474 • Improve collection autodiscovery for servers without full support.
2476 Version 0.2.1
2478 released on 05 July 2014
2479 • Fix bug where vdirsyncer shows empty addressbooks when using CardDAV
2481 with Zimbra.
2482 • Fix infinite loop when password doesn't exist in system keyring.
2484 • Colorized errors, warnings and debug messages.
2486 • vdirsyncer now depends on the click package instead of argvard.
2488 Version 0.2.0
2490 released on 12 June 2014
2491 • vdirsyncer now depends on the icalendar package from PyPI, to get rid
2493 of its own broken parser.
2494 • vdirsyncer now also depends on requests_toolbelt. This makes it pos‐
2496 sible to guess the authentication type instead of blankly assuming
2497 basic.
2498 • Fix a semi-bug in caldav and carddav storages where a tuple (href,
2500 etag) instead of the proper etag would have been returned from the
2501 upload method. vdirsyncer might do unnecessary copying when upgrad‐
2502 ing to this version.
2503 • Add the storage singlefile. See issue #48.
2505 • The collections parameter for pair sections now accepts the special
2507 values from a and from b for automatically discovering collections.
2508 See Pair Section.
2509 • The read_only parameter was added to storage sections. See Storage
2511 Section.
2512 Version 0.1.5
2514 released on 14 May 2014
2515 • Introduced changelogs
2517 • Many bugfixes
2519 • Many doc fixes
2521 • vdirsyncer now doesn't necessarily need UIDs anymore for synchroniza‐
2523 tion.
2524 • vdirsyncer now aborts if one collection got completely emptied be‐
2526 tween synchronizations. See issue #42.
2527
2529 Contributors
2530 In alphabetical order:
2531 • Ben Boeckel
2533 • Christian Geier
2535 • Clément Mondon
2537 • Hugo Osvaldo Barrera
2539 • Julian Mehne
2541 • Malte Kiefer
2543 • Marek Marczykowski-Górecki
2545 • Markus Unterwaditzer
2547 • Michael Adler
2549 • Thomas Weißschuh
2551 Special thanks goes to:
2553 • FastMail sponsors a paid account for testing their servers.
2555 • Packagecloud provide repositories for vdirsyncer's Debian packages.
2557 License
2559 Copyright (c) 2014-2020 by Markus Unterwaditzer & contributors. See AU‐
2560 THORS.rst for more details.
2561 Some rights reserved.
2563 Redistribution and use in source and binary forms of the software as
2565 well as documentation, with or without modification, are permitted pro‐
2566 vided that the following conditions are met:
2567 • Redistributions of source code must retain the above copyright no‐
2569 tice, this list of conditions and the following disclaimer.
2570 • Redistributions in binary form must reproduce the above copyright no‐
2572 tice, this list of conditions and the following disclaimer in the
2573 documentation and/or other materials provided with the distribution.
2574 • The names of the contributors may not be used to endorse or promote
2576 products derived from this software without specific prior written
2577 permission.
2578 THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS
2580 AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUD‐
2581 ING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
2582 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
2583 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, IN‐
2584 CIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
2585 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
2586 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
2587 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2588 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2589 OF THIS SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY
2590 OF SUCH DAMAGE.
2591
2593 If you found my work useful, please consider donating. Thank you!
2594 • Bitcoin: 16sSHxZm263WHR9P9PJjCxp64jp9ooXKVt
2596 • PayPal.me
2598 • Bountysource is useful for funding work on a specific GitHub issue.
2600 • There's also Bountysource Salt, for one-time and recurring dona‐
2602 tions.
2603 • Donations via Bountysource are publicly listed. Use PayPal if you
2605 dislike that.
2606 • Flattr or Gratipay can be used for recurring donations.
2608
2610 Markus Unterwaditzer
2611
2613 2014-2022, Markus Unterwaditzer & contributors
26140.18 Aug 17, 2022 VDIRSYNCER(1)