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 debian-urllib3).
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 problems page if anything doesn't work like
199 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 supported-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_config 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 collections_tutorial.
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_tutorial.
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 partial_sync_tutorial.
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 supported-servers, as some servers may not work
771 well.
772 caldav CalDAV.
774 [storage example_for_caldav]
776 type = "caldav"
777 #start_date = null
778 #end_date = null
779 #item_types = []
780 url = "..."
781 #username = ""
782 #password = ""
783 #verify = true
784 #auth = null
785 #useragent = "vdirsyncer/0.16.4"
786 #verify_fingerprint = null
787 #auth_cert = null
788 You can set a timerange to synchronize with the parameters
790 start_date and end_date. Inside those parameters, you can use
791 any Python expression to return a valid datetime.datetime ob‐
792 ject. For example, the following would synchronize the timerange
793 from one year in the past to one year in the future:
794 start_date = "datetime.now() - timedelta(days=365)"
796 end_date = "datetime.now() + timedelta(days=365)"
797 Either both or none have to be specified. The default is to syn‐
799 chronize everything.
800 You can set item_types to restrict the kind of items you want to
802 synchronize. For example, if you want to only synchronize events
803 (but don't download any tasks from the server), set item_types =
804 ["VEVENT"]. If you want to synchronize events and tasks, but
805 have some VJOURNAL items on the server you don't want to syn‐
806 chronize, use item_types = ["VEVENT", "VTODO"].
807 Parameters
809 • start_date -- Start date of timerange to show, default
811 -inf.
812 • end_date -- End date of timerange to show, default
814 +inf.
815 • item_types -- Kind of items to show. The default, the
817 empty list, is to show all. This depends on particular
818 features on the server, the results are not validated.
819 • url -- Base URL or an URL to a calendar.
821 • username -- Username for authentication.
823 • password -- Password for authentication.
825 • verify -- Verify SSL certificate, default True. This
827 can also be a local path to a self-signed SSL certifi‐
828 cate. See ssl-tutorial for more information.
829 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
831 of the expected server certificate. See ssl-tutorial
832 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-tutorial for more information.
871 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
873 of the expected server certificate. See ssl-tutorial
874 for more information.
875 • auth -- Optional. Either basic, digest or guess. The
877 default is preemptive Basic auth, sending credentials
878 even if server didn't request them. This saves from an
879 additional roundtrip per request. Consider setting
880 guess if this causes issues with your server.
881 • auth_cert -- Optional. Either a path to a certificate
883 with a client certificate and the key or a list of
884 paths to the files with them.
885 • useragent -- Default vdirsyncer.
887 Google
889 Vdirsyncer supports synchronization with Google calendars with the re‐
890 striction that VTODO files are rejected by the server.
891 Synchronization with Google contacts is less reliable due to negligence
893 of Google's CardDAV API. Google's CardDAV implementation is allegedly a
894 disaster in terms of data safety. See this blog post for the details.
895 Always back up your data.
896 At first run you will be asked to authorize application for Google ac‐
898 count access.
899 To use this storage type, you need to install some additional dependen‐
901 cies:
902 pip install vdirsyncer[google]
904 Furthermore you need to register vdirsyncer as an application yourself
906 to obtain client_id and client_secret, as it is against Google's Terms
907 of Service to hardcode those into opensource software [googleterms]:
908 1. Go to the Google API Manager and create a new project under any
910 name.
911 2. Within that project, enable the "CalDAV" and "CardDAV" APIs (not the
913 Calendar and Contacts APIs, those are different and won't work).
914 There should be a searchbox where you can just enter those terms.
915 3. In the sidebar, select "Credentials" and create a new "OAuth Client
917 ID". The application type is "Other".
918 You'll be prompted to create a OAuth consent screen first. Fill out
920 that form however you like.
921 4. Finally you should have a Client ID and a Client secret. Provide
923 these in your storage config.
924 The token_file parameter should be a filepath where vdirsyncer can
926 later store authentication-related data. You do not need to create the
927 file itself or write anything to it.
928 [googleterms]
930 See ToS, section "Confidential Matters".
931 NOTE:
933 You need to configure which calendars Google should offer vdirsyncer
934 using a rather hidden settings page.
935 google_calendar
937 Google calendar.
938 [storage example_for_google_calendar]
940 type = "google_calendar"
941 token_file = "..."
942 client_id = "..."
943 client_secret = "..."
944 #start_date = null
945 #end_date = null
946 #item_types = []
947 Please refer to caldav regarding the item_types and timerange
949 parameters.
950 Parameters
952 • token_file -- A filepath where access tokens are
954 stored.
955 • client_id/client_secret -- OAuth credentials, obtained
957 from the Google API Manager.
958 google_contacts
960 Google contacts.
961 [storage example_for_google_contacts]
963 type = "google_contacts"
964 token_file = "..."
965 client_id = "..."
966 client_secret = "..."
967 Parameters
969 • token_file -- A filepath where access tokens are
971 stored.
972 • client_id/client_secret -- OAuth credentials, obtained
974 from the Google API Manager.
975 EteSync
977 EteSync is a new cloud provider for end to end encrypted contacts and
978 calendar storage. Vdirsyncer contains experimental support for it.
979 To use it, you need to install some optional dependencies:
981 pip install vdirsyncer[etesync]
983 On first usage you will be prompted for the service password and the
985 encryption password. Neither are stored.
986 etesync_contacts
988 Contacts for etesync.
989 [storage example_for_etesync_contacts]
991 email = ...
992 secrets_dir = ...
993 #server_path = ...
994 #db_path = ...
995 Parameters
997 • email -- The email address of your account.
999 • secrets_dir -- A directory where vdirsyncer can store
1001 the encryption key and authentication token.
1002 • server_url -- Optional. URL to the root of your custom
1004 server.
1005 • db_path -- Optional. Use a different path for the data‐
1007 base.
1008 etesync_calendars
1010 Calendars for etesync.
1011 [storage example_for_etesync_calendars]
1013 email = ...
1014 secrets_dir = ...
1015 #server_path = ...
1016 #db_path = ...
1017 Parameters
1019 • email -- The email address of your account.
1021 • secrets_dir -- A directory where vdirsyncer can store
1023 the encryption key and authentication token.
1024 • server_url -- Optional. URL to the root of your custom
1026 server.
1027 • db_path -- Optional. Use a different path for the data‐
1029 base.
1030 Local
1032 filesystem
1033 Saves each item in its own file, given a directory.
1034 [storage example_for_filesystem]
1036 type = "filesystem"
1037 path = "..."
1038 fileext = "..."
1039 #encoding = "utf-8"
1040 #post_hook = null
1041 #fileignoreext = ".tmp"
1042 Can be used with khal. See vdir for a more formal description of
1044 the format.
1045 Directories with a leading dot are ignored to make usage of e.g.
1047 version control easier.
1048 Parameters
1050 • path -- Absolute path to a vdir/collection. If this is
1052 used in combination with the collections parameter in a
1053 pair-section, this should point to a directory of vdirs
1054 instead.
1055 • fileext -- The file extension to use (e.g. .txt). Con‐
1057 tained in the href, so if you change the file extension
1058 after a sync, this will trigger a re-download of every‐
1059 thing (but should not cause data-loss of any kind). To
1060 be compatible with the vset format you have to either
1061 use .vcf or .ics. Note that metasync won't work if you
1062 use an empty string here.
1063 • encoding -- File encoding for items, both content and
1065 filename.
1066 • post_hook -- A command to call for each item creation
1068 and modification. The command will be called with the
1069 path of the new/updated file.
1070 • fileeignoreext -- The file extention to ignore. It is
1072 only useful if fileext is set to the empty string. The
1073 default is .tmp.
1074 singlefile
1076 Save data in single local .vcf or .ics file.
1077 The storage basically guesses how items should be joined in the
1079 file.
1080 New in version 0.1.6.
1082 NOTE:
1085 This storage is very slow, and that is unlikely to change.
1086 You should consider using filesystem if it fits your usecase.
1087 Parameters
1089 • path -- The filepath to the file to be written to. If
1091 collections are used, this should contain %s as a
1092 placeholder for the collection name.
1093 • encoding -- Which encoding the file should use. De‐
1095 faults to UTF-8.
1096 Example for syncing with caldav:
1098 [pair my_calendar]
1100 a = my_calendar_local
1101 b = my_calendar_remote
1102 collections = ["from a", "from b"]
1103 [storage my_calendar_local]
1105 type = "singlefile"
1106 path = ~/.calendars/%s.ics
1107 [storage my_calendar_remote]
1109 type = "caldav"
1110 url = https://caldav.example.org/
1111 #username =
1112 #password =
1113 Example for syncing with caldav using a null collection:
1115 [pair my_calendar]
1117 a = my_calendar_local
1118 b = my_calendar_remote
1119 [storage my_calendar_local]
1121 type = "singlefile"
1122 path = ~/my_calendar.ics
1123 [storage my_calendar_remote]
1125 type = "caldav"
1126 url = https://caldav.example.org/username/my_calendar/
1127 #username =
1128 #password =
1129 Read-only storages
1131 These storages don't support writing of their items, consequently
1132 read_only is set to true by default. Changing read_only to false on
1133 them leads to an error.
1134 http Use a simple .ics file (or similar) from the web. web‐
1136 cal://-calendars are supposed to be used with this, but you have
1137 to replace webcal:// with http://, or better, https://.
1138 [pair holidays]
1140 a = holidays_local
1141 b = holidays_remote
1142 collections = null
1143 [storage holidays_local]
1145 type = "filesystem"
1146 path = ~/.config/vdir/calendars/holidays/
1147 fileext = .ics
1148 [storage holidays_remote]
1150 type = "http"
1151 url = https://example.com/holidays_from_hicksville.ics
1152 Too many WebCAL providers generate UIDs of all VEVENT-components
1154 on-the-fly, i.e. all UIDs change every time the calendar is
1155 downloaded. This leads many synchronization programs to believe
1156 that all events have been deleted and new ones created, and ac‐
1157 cordingly causes a lot of unnecessary uploads and deletions on
1158 the other side. Vdirsyncer completely ignores UIDs coming from
1159 http and will replace them with a hash of the normalized item
1160 content.
1161 Parameters
1163 • url -- URL to the .ics file.
1165 • username -- Username for authentication.
1167 • password -- Password for authentication.
1169 • verify -- Verify SSL certificate, default True. This
1171 can also be a local path to a self-signed SSL certifi‐
1172 cate. See ssl-tutorial for more information.
1173 • verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
1175 of the expected server certificate. See ssl-tutorial
1176 for more information.
1177 • auth -- Optional. Either basic, digest or guess. The
1179 default is preemptive Basic auth, sending credentials
1180 even if server didn't request them. This saves from an
1181 additional roundtrip per request. Consider setting
1182 guess if this causes issues with your server.
1183 • auth_cert -- Optional. Either a path to a certificate
1185 with a client certificate and the key or a list of
1186 paths to the files with them.
1187 • useragent -- Default vdirsyncer.
1189
1191 The following section contains tutorials not explicitly about any par‐
1192 ticular core function of vdirsyncer. They usually show how to integrate
1193 vdirsyncer with third-party software. Because of that, it may be that
1194 the information regarding that other software only applies to specific
1195 versions of them.
1196 NOTE:
1198 Please contribute your own tutorials too! Pages are often only
1199 stubs and are lacking full examples.
1200 Client applications
1202 Vdirsyncer with Claws Mail
1203 First of all, Claws-Mail only supports read-only functions for vCards.
1204 It can only read contacts, but there's no editor.
1205 Preparation
1207 We need to install vdirsyncer, for that look here. Then we need to
1208 create some folders:
1209 mkdir ~/.vdirsyncer
1211 mkdir ~/.contacts
1212 Configuration
1214 Now we create the configuration for vdirsyncer. Open ~/.vdirsyncer/con‐
1215 fig with a text editor. The config should look like this:
1216 [general]
1218 status_path = "~/.vdirsyncer/status/"
1219 [storage local]
1221 type = "singlefile"
1222 path = "~/.contacts/%s.vcf"
1223 [storage online]
1225 type = "carddav"
1226 url = "CARDDAV_LINK"
1227 username = "USERNAME"
1228 password = "PASSWORD"
1229 read_only = true
1230 [pair contacts]
1232 a = "local"
1233 b = "online"
1234 collections = ["from a", "from b"]
1235 conflict_resolution = "b wins"
1236 • In the general section, we define the status folder path, for discov‐
1238 ered collections and generally stuff that needs to persist between
1239 syncs.
1240 • In the local section we define that all contacts should be sync in a
1242 single file and the path for the contacts.
1243 • In the online section you must change the url, username and password
1245 to your setup. We also set the storage to read-only such that no
1246 changes get synchronized back. Claws-Mail should not be able to do
1247 any changes anyway, but this is one extra safety step in case files
1248 get corrupted or vdirsyncer behaves erratically. You can leave that
1249 part out if you want to be able to edit those files locally.
1250 • In the last section we configure that online contacts win in a con‐
1252 flict situation. Configure this part however you like. A correct
1253 value depends on which side is most likely to be up-to-date.
1254 Sync
1256 Now we discover and sync our contacts:
1257 vdirsyncer discover contacts
1259 vdirsyncer sync contacts
1260 Claws Mail
1262 Open Claws-Mail. Go to Tools => Addressbook.
1263 Click on Addressbook => New vCard. Choose a name for the book.
1265 Then search for the for the vCard in the folder ~/.contacts/. Click ok,
1267 and you we will see your contacts.
1268 NOTE:
1270 Claws-Mail shows only contacts that have a mail address.
1271 Crontab
1273 On the end we create a crontab, so that vdirsyncer syncs automatically
1274 every 30 minutes our contacts:
1275 crontab -e
1277 On the end of that file enter this line:
1279 */30 * * * * /usr/local/bin/vdirsyncer sync > /dev/null
1281 And you're done!
1283 Running as a systemd.timer
1285 vdirsyncer includes unit files to run at an interval (by default every
1286 15±5 minutes).
1287 NOTE:
1289 These are not installed when installing via pip, only via distribu‐
1290 tion packages. If you installed via pip, or your distribution
1291 doesn't ship systemd unit files, you'll need to download
1292 vdirsyncer.service and vdirsyncer.timer into either /etc/sys‐
1293 temd/user/ or ~/.local/share/systemd/user.
1294 Activation
1296 To activate the timer, just run systemctl --user enable
1297 vdirsyncer.timer. To see logs of previous runs, use journalctl --user
1298 -u vdirsyncer.
1299 Configuration
1301 It's quite possible that the default "every fifteen minutes" interval
1302 isn't to your liking. No default will suit everybody, but this is con‐
1303 figurable by simply running:
1304 systemctl --user edit vdirsyncer.timer
1306 This will open a blank editor, where you can override the timer by in‐
1308 cluding:
1309 OnBootSec=5m # This is how long after boot the first run takes place.
1311 OnUnitActiveSec=15m # This is how often subsequent runs take place.
1312 Todoman
1314 The iCalendar format also supports saving tasks in form of VTODO-en‐
1315 tries, with the same file extension as normal events: .ics. Many CalDAV
1316 servers support synchronizing tasks, vdirsyncer does too.
1317 todoman is a CLI task manager supporting vdir. Its interface is similar
1319 to the ones of Taskwarrior or the todo.txt CLI app. You can use
1320 filesystem with it.
1321 Setting up vdirsyncer
1323 For this tutorial we will use NextCloud.
1324 Assuming a config like this:
1326 [general]
1328 status_path = "~/.vdirsyncer/status/"
1329 [pair calendars]
1331 conflict_resolution = "b wins"
1332 a = "calendars_local"
1333 b = "calendars_dav"
1334 collections = ["from b"]
1335 metadata = ["color", "displayname"]
1336 [storage calendars_local]
1338 type = "filesystem"
1339 path = "~/.calendars/"
1340 fileext = ".ics"
1341 [storage calendars_dav]
1343 type = "caldav"
1344 url = "https://nextcloud.example.net/"
1345 username = "..."
1346 password = "..."
1347 vdirsyncer sync will then synchronize the calendars of your NextCloud
1349 instance to subfolders of ~/.calendar/.
1350 Setting up todoman
1352 Write this to ~/.config/todoman/todoman.conf:
1353 [main]
1355 path = ~/.calendars/*
1356 The glob pattern in path will match all subfolders in ~/.calendars/,
1358 which is exactly the tasklists we want. Now you can use todoman as de‐
1359 scribed in its documentation and run vdirsyncer sync to synchronize the
1360 changes to NextCloud.
1361 Other clients
1363 The following client applications also synchronize over CalDAV:
1364 • The Tasks-app found on iOS
1366 • OpenTasks for Android
1368 • The Tasks-app for NextCloud's web UI
1370 Further applications, with missing pages:
1372 • khal, a CLI calendar application supporting vdir. You can use
1374 filesystem with it.
1375 • Many graphical calendar apps such as dayplanner, Orage or rainlendar
1377 save a calendar in a single .ics file. You can use singlefile with
1378 those.
1379 • khard, a commandline addressbook supporting vdir. You can use
1381 filesystem with it.
1382 • contactquery.c, a small program explicitly written for querying vdirs
1384 from mutt.
1385 • mates, a commandline addressbook supporting vdir.
1387 • vdirel, access vdir contacts from Emacs.
1389 Servers
1391 Baikal
1392 Vdirsyncer is continuously tested against the latest version of Baikal.
1393 • Baikal up to 0.2.7 also uses an old version of SabreDAV, with the
1395 same issue as ownCloud, see issue #160. This issue is fixed in later
1396 versions.
1397 DavMail (Exchange, Outlook)
1399 DavMail is a proxy program that allows you to use Card- and CalDAV
1400 clients with Outlook. That allows you to use vdirsyncer with Outlook.
1401 In practice your success with DavMail may wildly vary. Depending on
1403 your Exchange server you might get confronted with weird errors of all
1404 sorts (including data-loss).
1405 Make absolutely sure you use the latest DavMail:
1407 [storage outlook]
1409 type = "caldav"
1410 url = "http://localhost:1080/users/user@example.com/calendar/"
1411 username = "user@example.com"
1412 password = "..."
1413 • Older versions of DavMail handle URLs case-insensitively. See issue
1415 #144.
1416 • DavMail is handling malformed data on the Exchange server very
1418 poorly. In such cases the Calendar Checking Tool for Outlook might
1419 help.
1420 • In some cases, you may see errors about duplicate events. It may look
1422 something like this:
1423 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:
1425 error:
1426 error: vdirsyncer repair my_calendar_remote/calendar
1427 error:
1428 error: But make sure to have a backup of your data in some form. The offending hrefs are:
1429 [...]
1430 In order to fix this, you can try the
1432 Remove-DuplicateAppointments.ps1 PowerShell script that Microsoft has
1433 come up with in order to remove duplicates.
1434 FastMail
1436 Vdirsyncer is continuously tested against FastMail, thanks to them for
1437 providing a free account for this purpose. There are no known issues
1438 with it. FastMail's support pages provide the settings to use:
1439 [storage cal]
1441 type = "caldav"
1442 url = "https://caldav.fastmail.com/"
1443 username = "..."
1444 password = "..."
1445 [storage card]
1447 type = "carddav"
1448 url = "https://carddav.fastmail.com/"
1449 username = "..."
1450 password = "..."
1451 Google
1453 Using vdirsyncer with Google Calendar is possible as of 0.10, but it is
1454 not tested frequently. You can use google_contacts and google_calendar.
1455 For more information see issue #202 and issue #8.
1457 iCloud
1459 Vdirsyncer is regularly tested against iCloud.
1460 [storage cal]
1462 type = "caldav"
1463 url = "https://caldav.icloud.com/"
1464 username = "..."
1465 password = "..."
1466 [storage card]
1468 type = "carddav"
1469 url = "https://contacts.icloud.com/"
1470 username = "..."
1471 password = "..."
1472 Problems:
1474 • Vdirsyncer can't do two-factor auth with iCloud (there doesn't seem
1476 to be a way to do two-factor auth over the DAV APIs) You'll need to
1477 use app-specific passwords instead.
1478 • iCloud has a few special requirements when creating collections. In
1480 principle vdirsyncer can do it, but it is recommended to create them
1481 from an Apple client (or the iCloud web interface).
1482 • iCloud requires a minimum length of collection names.
1484 • Calendars created by vdirsyncer cannot be used as tasklists.
1486 nextCloud
1488 Vdirsyncer is continuously tested against the latest version of
1489 nextCloud:
1490 [storage cal]
1492 type = "caldav"
1493 url = "https://nextcloud.example.com/"
1494 username = "..."
1495 password = "..."
1496 [storage card]
1498 type = "carddav"
1499 url = "https://nextcloud.example.com/"
1500 • WebCAL-subscriptions can't be discovered by vdirsyncer. See this rel‐
1502 evant issue.
1503 ownCloud
1505 Vdirsyncer is continuously tested against the latest version of
1506 ownCloud:
1507 [storage cal]
1509 type = "caldav"
1510 url = "https://example.com/remote.php/dav/"
1511 username = ...
1512 password = ...
1513 [storage card]
1515 type = "carddav"
1516 url = "https://example.com/remote.php/dav/"
1517 username = ...
1518 password = ...
1519 • Versions older than 7.0.0: ownCloud uses SabreDAV, which had problems
1521 detecting collisions and race-conditions. The problems were reported
1522 and are fixed in SabreDAV's repo, and the corresponding fix is also
1523 in ownCloud since 7.0.0. See issue #16 for more information.
1524 Radicale
1526 Radicale is a very lightweight server, however, it intentionally
1527 doesn't implement the CalDAV and CardDAV standards completely, which
1528 might lead to issues even with very well-written clients. Apart from
1529 its non-conformity with standards, there are multiple other problems
1530 with its code quality and the way it is maintained. Consider using e.g.
1531 xandikos instead.
1532 That said, vdirsyncer is continuously tested against the git version
1534 and the latest PyPI release of Radicale.
1535 • Vdirsyncer can't create collections on Radicale.
1537 • Radicale doesn't support time ranges in the calendar-query of CalDAV,
1539 so setting start_date and end_date for caldav will have no or unpre‐
1540 dicted consequences.
1541 • Versions of Radicale older than 0.9b1 choke on RFC-conform queries
1543 for all items of a collection.
1544 You have to set item_types = ["VTODO", "VEVENT"] in caldav for
1546 vdirsyncer to work with those versions.
1547 Xandikos
1549 Xandikos is a lightweight, yet complete CalDAV and CardDAV server,
1550 backed by git. Vdirsyncer is continuously tested against its latest
1551 version.
1552 After running ./bin/xandikos --defaults -d $HOME/dav, you should be
1554 able to point vdirsyncer against the root of Xandikos like this:
1555 [storage cal]
1557 type = "caldav"
1558 url = "https://xandikos.example.com/"
1559 username = "..."
1560 password = "..."
1561 [storage card]
1563 type = "carddav"
1564 url = "https://xandikos.example.com/"
1565 username = "..."
1566 password = "..."
1567
1569 For any unanswered questions or problems, see contact.
1570 Requests-related ImportErrors
1572 ImportError: No module named packages.urllib3.poolmanager
1573 ImportError: cannot import name iter_field_objects
1575 Debian and nowadays even other distros make modifications to the re‐
1577 quests package that don't play well with packages assuming a normal re‐
1578 quests. This is due to stubbornness on both sides.
1579 See issue #82 and issue #140 for past discussions. You have one option
1581 to work around this, that is, to install vdirsyncer in a virtualenv,
1582 see manual-installation.
1583
1585 NOTE:
1586 • Please read contact for questions and support requests.
1588 • All participants must follow the pimutils Code of Conduct.
1590 The issue tracker
1592 We use GitHub issues for organizing bug reports and feature requests.
1593 The following labels are of interest:
1595 • "Planning" is for issues that are still undecided, but where at least
1597 some discussion exists.
1598 • "Blocked" is for issues that can't be worked on at the moment because
1600 some other unsolved problem exists. This problem may be a bug in some
1601 software dependency, for instance.
1602 • "Ready" contains issues that are ready to work on.
1604 If you just want to get started with contributing, the "ready" issues
1606 are an option. Issues that are still in "Planning" are also an option,
1607 but require more upfront thinking and may turn out to be impossible to
1608 solve, or at least harder than anticipated. On the flip side those tend
1609 to be the more interesting issues as well, depending on how one looks
1610 at it.
1611 All of those labels are also available as a kanban board on waffle.io.
1613 It is really just an alternative overview over all issues, but might be
1614 easier to comprehend.
1615 Feel free to contact me or comment on the relevant issues for further
1617 information.
1618 Reporting bugs
1620 • Make sure your problem isn't already listed in problems.
1621 • Make sure you have the absolutely latest version of vdirsyncer. For
1623 users of some Linux distributions such as Debian or Fedora this may
1624 not be the version that your distro offers. In those cases please
1625 file a bug against the distro package, not against upstream
1626 vdirsyncer.
1627 • Use --verbosity=DEBUG when including output from vdirsyncer.
1629 Suggesting features
1631 If you're suggesting a feature, keep in mind that vdirsyncer tries not
1632 to be a full calendar or contacts client, but rather just the piece of
1633 software that synchronizes all the data. Take a look at the documenta‐
1634 tion for software working with vdirsyncer.
1635 Submitting patches, pull requests
1637 • Discuss everything in the issue tracker first (or contact me somehow
1638 else) before implementing it.
1639 • Make sure the tests pass. See below for running them.
1641 • But not because you wrote too few tests.
1643 • Add yourself to AUTHORS.rst, and add a note to CHANGELOG.rst too.
1645 Running tests, how to set up your development environment
1647 For many patches, it might suffice to just let CI run the tests. How‐
1648 ever, CI is slow, so you might want to run them locally too. For this,
1649 set up a virtualenv and run this inside of it:
1650 # install:
1652 # - vdirsyncer from the repo into the virtualenv
1653 # - stylecheckers (flake8) and code formatters (autopep8)
1654 make install-dev
1655 # Install git commit hook for some extra linting and checking
1657 pre-commit install
1658 # Install development dependencies
1660 make install-dev
1661 Then you can run:
1663 make test # The normal testsuite
1665 make style # Stylechecker
1666 make docs # Build the HTML docs, output is at docs/_build/html/
1667 The Makefile has a lot of options that allow you to control which tests
1669 are run, and which servers are tested. Take a look at its code where
1670 they are all initialized and documented.
1671 To tests against a specific DAV server, use DAV_SERVER:
1673 make DAV_SERVER=xandikos test
1675 The server will be initialised in a docker container and terminated at
1677 the end of the test suite.
1678 If you have any questions, feel free to open issues about it.
1680 Structure of the testsuite
1682 Within tests/, there are three main folders:
1683 • system contains system- and also integration tests. A rough rule is:
1685 If the test is using temporary files, put it here.
1686 • unit, where each testcase tests a single class or function.
1688 • storage runs a generic storage testsuite against all storages.
1690 The reason for this separation is: We are planning to generate separate
1692 coverage reports for each of those testsuites. Ideally unit would gen‐
1693 erate palatable coverage of the entire codebase on its own, and the
1694 combination of system and storage as well.
1695
1697 This document describes a standard for storing calendars and contacts
1698 on a filesystem, with the main goal of being easy to implement.
1699 Vdirsyncer synchronizes to vdirs via filesystem. Each vdir (basically
1701 just a directory with some files in it) represents a calendar or ad‐
1702 dressbook.
1703 Basic Structure
1705 The main folder (root) contains an arbitrary number of subfolders (col‐
1706 lections), which contain only files (items). Synonyms for "collection"
1707 may be "addressbook" or "calendar".
1708 An item is:
1710 • A vCard file, in which case the file extension must be .vcf, or
1712 • An iCalendar file, in which case the file extension must be .ics.
1714 An item should contain a UID property as described by the vCard and
1716 iCalendar standards. If it contains more than one UID property, the
1717 values of those must not differ.
1718 The file must contain exactly one event, task or contact. In most cases
1720 this also implies only one VEVENT/VTODO/VCARD component per file, but
1721 e.g. recurrence exceptions would require multiple VEVENT components
1722 per event.
1723 The filename should have similar properties as the UID of the file con‐
1725 tent. However, there is no requirement for these two to be the same.
1726 Programs may choose to store additional metadata in that filename, how‐
1727 ever, at the same time they must not assume that the metadata they in‐
1728 cluded will be preserved by other programs.
1729 Metadata
1731 Any of the below metadata files may be absent. None of the files listed
1732 below have any file extensions.
1733 • A file called color inside the vdir indicates the vdir's color, a
1735 property that is only relevant in UI design.
1736 Its content is an ASCII-encoded hex-RGB value of the form #RRGGBB.
1738 For example, a file content of #FF0000 indicates that the vdir has a
1739 red (user-visible) color. No short forms or informal values such as
1740 red (as known from CSS, for example) are allowed. The prefixing #
1741 must be present.
1742 • A file called displayname contains a UTF-8 encoded label that may be
1744 used to represent the vdir in UIs.
1745 Writing to vdirs
1747 Creating and modifying items or metadata files should happen
1748 atomically.
1749 Writing to a temporary file on the same physical device, and then mov‐
1751 ing it to the appropriate location is usually a very effective solu‐
1752 tion. For this purpose, files with the extension .tmp may be created
1753 inside collections.
1754 When changing an item, the original filename must be used.
1756 Reading from vdirs
1758 • Any file ending with the .tmp or no file extension must not be
1759 treated as an item.
1760 • The ident part of the filename should not be parsed to improve the
1762 speed of item lookup.
1763 Considerations
1765 The primary reason this format was chosen is due to its compatibility
1766 with the CardDAV and CalDAV standards.
1767 Performance
1769 Currently, vdirs suffer from a rather major performance problem, one
1770 which current implementations try to mitigate by building up indices of
1771 the collections for faster search and lookup.
1772 The reason items' filenames don't contain any extra information is sim‐
1774 ple: The solutions presented induced duplication of data, where one du‐
1775 plicate might become out of date because of bad implementations. As it
1776 stands right now, an index format could be formalized separately
1777 though.
1778 vdirsyncer doesn't really have to bother about efficient item lookup,
1780 because its synchronization algorithm needs to fetch the whole list of
1781 items anyway. Detecting changes is easily implemented by checking the
1782 files' modification time.
1783
1785 Thank you very much for packaging vdirsyncer! The following guidelines
1786 should help you to avoid some common pitfalls.
1787 If you find yourself needing to patch anything, or going in a different
1789 direction, please open an issue so we can also address in a way that
1790 works for everyone. Otherwise we get bug reports for code or scenarios
1791 that don't exist in upstream vdirsycner.
1792 Obtaining the source code
1794 The main distribution channel is PyPI, and source tarballs can be ob‐
1795 tained there. We mirror the same package tarball and wheel as GitHub
1796 releases. Please do not confuse these with the auto-generated GitHub
1797 "Source Code" tarball. Those are missing some important metadata and
1798 your build will fail.
1799 We give each release a tag in the git repo. If you want to get notified
1801 of new releases, GitHub's feed is a good way.
1802 Tags will be signed by the maintainer who is doing the release (start‐
1804 ing with 0.16.8), and generation of the tarball and wheel is done by
1805 CI. Hence, only the tag itself is signed.
1806 Dependency versions
1808 As with most Python packages, setup.py denotes the dependencies of
1809 vdirsyncer. It also contains lower-bound versions of each dependency.
1810 Older versions will be rejected by the testsuite.
1811 Testing
1813 Everything testing-related goes through the Makefile in the root of the
1814 repository or PyPI package. Trying to e.g. run pytest directly will re‐
1815 quire a lot of environment variables to be set (for configuration) and
1816 you probably don't want to deal with that.
1817 You can install the all development dependencies with:
1819 make install-dev
1821 You probably don't want this since it will use pip to download the de‐
1823 pendencies. Alternatively you can find the testing dependencies in
1824 test-requirements.txt, again with lower-bound version requirements.
1825 You also have to have vdirsyncer fully installed at this point. Merely
1827 cd-ing into the tarball will not be sufficient.
1828 Running the tests happens with:
1830 make test
1832 Hypothesis will randomly generate test input. If you care about deter‐
1834 ministic tests, set the DETERMINISTIC_TESTS variable to "true":
1835 make DETERMINISTIC_TESTS=true test
1837 There are a lot of additional variables that allow you to test
1839 vdirsyncer against a particular server. Those variables are not "sta‐
1840 ble" and may change drastically between minor versions. Just don't use
1841 them, you are unlikely to find bugs that vdirsyncer's CI hasn't found.
1842 Documentation
1844 Using Sphinx you can generate the documentation you're reading right
1845 now in a variety of formats, such as HTML, PDF, or even as a manpage.
1846 That said, I only take care of the HTML docs' formatting.
1847 You can find a list of dependencies in docs-requirements.txt. Again,
1849 you can install those using pip with:
1850 make install-docs
1852 Then change into the docs/ directory and build whatever format you want
1854 using the Makefile in there (run make for the formats you can build).
1855 Contrib files
1857 Reference systemd.service and systemd.timer unit files are provided. It
1858 is recommended to install this if your distribution is systemd-based.
1859
1861 • The #pimutils IRC channel on Libera.Chat might be active, depending
1862 on your timezone. Use it for support and general (including
1863 off-topic) discussion.
1864 • Open a GitHub issue for concrete bug reports and feature requests.
1866 • Lastly, you can also contact the author directly. Do this for secu‐
1868 rity issues. If that doesn't work out (i.e. if I don't respond within
1869 one week), use contact@pimutils.org.
1870
1872 This changelog only contains information that might be useful to end
1873 users and package maintainers. For further info, see the git commit
1874 log.
1875 Package maintainers and users who have to manually update their instal‐
1877 lation may want to subscribe to GitHub's tag feed.
1878 Version 0.18.0
1880 Note: Version 0.17 has some alpha releases but ultimately was never fi‐
1881 nalised. 0.18 actually continues where 0.16 left off.
1882 • Support for Python 3.5 and 3.6 has been dropped. This release mostly
1884 focuses on keeping vdirsyncer compatible with newer environments.
1885 • click 8 and click-threading 0.5.0 are now required.
1887 • For those using pipsi, we now recommend using pipx, it's successor.
1889 • Python 3.9 is now supported.
1891 • Our Debian/Ubuntu build scripts have been updated. New versions
1893 should be pushed to those repositories soon.
1894 Version 0.16.8
1896 released 09 June 2020
1897 • Support Python 3.7 and 3.8.
1899 This release is functionally identical to 0.16.7. It's been tested
1901 with recent Python versions, and has been marked as supporting them. It
1902 will also be the final release supporting Python 3.5 and 3.6.
1903 Version 0.16.7
1905 released on 19 July 2018
1906 • Fixes for Python 3.7
1908 Version 0.16.6
1910 released on 13 June 2018
1911 • Packagers: Documentation building no longer needs a working installa‐
1913 tion of vdirsyncer.
1914 Version 0.16.5
1916 released on 13 June 2018
1917 • Packagers: click-log 0.3 is required.
1919 • All output will now happen on stderr (because of the upgrade of
1921 click-log).
1922 Version 0.16.4
1924 released on 05 February 2018
1925 • Fix tests for new Hypothesis version. (Literally no other change in‐
1927 cluded)
1928 Version 0.16.3
1930 released on 03 October 2017
1931 • First version with custom Debian and Ubuntu packages. See issue #663.
1933 • Remove invalid ASCII control characters from server responses. See
1935 issue #626.
1936 • packagers: Python 3.3 is no longer supported. See pull request #674.
1938 Version 0.16.2
1940 released on 24 August 2017
1941 • Fix crash when using daterange or item_type filters in google_calen‐
1943 dar, see issue #657.
1944 • Packagers: Fixes for new version 0.2.0 of click-log. The version re‐
1946 quirements for the dependency click-log changed.
1947 Version 0.16.1
1949 released on 8 August 2017
1950 • Removed remoteStorage support, see issue #647.
1952 • Fixed test failures caused by latest requests version, see issue
1954 #660.
1955 Version 0.16.0
1957 released on 2 June 2017
1958 • Strip METHOD:PUBLISH added by some calendar providers, see issue
1960 #502.
1961 • Fix crash of Google storages when saving token file.
1963 • Make DAV discovery more RFC-conformant, see pull request #585.
1965 • Vdirsyncer is now tested against Xandikos, see pull request #601.
1967 • Subfolders with a leading dot are now ignored during discover for
1969 filesystem storage. This makes it easier to combine it with version
1970 control.
1971 • Statuses are now stored in a sqlite database. Old data is automati‐
1973 cally migrated. Users with really large datasets should encounter
1974 performance improvements. This means that sqlite3 is now a dependency
1975 of vdirsyncer.
1976 • Vdirsyncer is now licensed under the 3-clause BSD license, see issue
1978 #610.
1979 • Vdirsyncer now includes experimental support for EteSync, see pull
1981 request #614.
1982 • Vdirsyncer now uses more filesystem metadata for determining whether
1984 an item changed. You will notice a possibly heavy CPU/IO spike on the
1985 first sync after upgrading.
1986 • Packagers: Reference systemd.service and systemd.timer unit files are
1988 provided. It is recommended to install these as documentation if your
1989 distribution is systemd-based.
1990 Version 0.15.0
1992 released on 28 February 2017
1993 • Deprecated syntax for configuration values is now completely re‐
1995 jected. All values now have to be valid JSON.
1996 • A few UX improvements for Google storages, see issue #549 and issue
1998 #552.
1999 • Fix collection discovery for google_contacts, see issue #564.
2001 • iCloud is now tested on Travis, see issue #567.
2003 Version 0.14.1
2005 released on 05 January 2017
2006 • vdirsyncer repair no longer changes "unsafe" UIDs by default, an ex‐
2008 tra option has to be specified. See issue #527.
2009 • A lot of important documentation updates.
2011 Version 0.14.0
2013 released on 26 October 2016
2014 • vdirsyncer sync now continues other uploads if one upload failed.
2016 The exit code in such situations is still non-zero.
2017 • Add partial_sync option to pair section. See the config docs.
2019 • Vdirsyncer will now warn if there's a string without quotes in your
2021 config. Please file issues if you find documentation that uses un‐
2022 quoted strings.
2023 • Fix an issue that would break khal's config setup wizard.
2025 Version 0.13.1
2027 released on 30 September 2016
2028 • Fix a bug that would completely break collection discovery.
2030 Version 0.13.0
2032 released on 29 September 2016
2033 • Python 2 is no longer supported at all. See issue #219.
2035 • Config sections are now checked for duplicate names. This also means
2037 that you cannot have a storage section [storage foo] and a pair [pair
2038 foo] in your config, they have to have different names. This is done
2039 such that console output is always unambiguous. See issue #459.
2040 • Custom commands can now be used for conflict resolution during sync.
2042 See issue #127.
2043 • http now completely ignores UIDs. This avoids a lot of unnecessary
2045 down- and uploads.
2046 Version 0.12.1
2048 released on 20 August 2016
2049 • Fix a crash for Google and DAV storages. See pull request #492.
2051 • Fix an URL-encoding problem with DavMail. See issue #491.
2053 Version 0.12
2055 released on 19 August 2016
2056 • singlefile now supports collections. See pull request #488.
2058 Version 0.11.3
2060 released on 29 July 2016
2061 • Default value of auth parameter was changed from guess to basic to
2063 resolve issues with the Apple Calendar Server (issue #457) and im‐
2064 prove performance. See issue #461.
2065 • Packagers: The click-threading requirement is now >=0.2. It was in‐
2067 correct before. See issue #478.
2068 • Fix a bug in the DAV XML parsing code that would make vdirsyncer
2070 crash on certain input. See issue #480.
2071 • Redirect chains should now be properly handled when resolving
2073 well-known URLs. See pull request #481.
2074 Version 0.11.2
2076 released on 15 June 2016
2077 • Fix typo that would break tests.
2079 Version 0.11.1
2081 released on 15 June 2016
2082 • Fix a bug in collection validation.
2084 • Fix a cosmetic bug in debug output.
2086 • Various documentation improvements.
2088 Version 0.11.0
2090 released on 19 May 2016
2091 • Discovery is no longer automatically done when running vdirsyncer
2093 sync. vdirsyncer discover now has to be explicitly called.
2094 • Add a .plist example for Mac OS X.
2096 • Usage under Python 2 now requires a special config parameter to be
2098 set.
2099 • Various deprecated configuration parameters do no longer have spe‐
2101 cialized errormessages. The generic error message for unknown parame‐
2102 ters is shown.
2103 • Vdirsyncer no longer warns that the passwordeval parameter has been
2105 renamed to password_command.
2106 • The keyring fetching strategy has been dropped some versions ago,
2108 but the specialized error message has been dropped.
2109 • An old status format from version 0.4 is no longer supported. If
2111 you're experiencing problems, just delete your status folder.
2112 Version 0.10.0
2114 released on 23 April 2016
2115 • New storage types google_calendar and google_contacts have been
2117 added.
2118 • New global command line option --config, to specify an alternative
2120 config file. See issue #409.
2121 • The collections parameter can now be used to synchronize differ‐
2123 ently-named collections with each other.
2124 • Packagers: The lxml dependency has been dropped.
2126 • XML parsing is now a lot stricter. Malfunctioning servers that used
2128 to work with vdirsyncer may stop working.
2129 Version 0.9.3
2131 released on 22 March 2016
2132 • singlefile and http now handle recurring events properly.
2134 • Fix a typo in the packaging guidelines.
2136 • Moved to pimutils organization on GitHub. Old links should redirect,
2138 but be aware of client software that doesn't properly handle redi‐
2139 rects.
2140 Version 0.9.2
2142 released on 13 March 2016
2143 • Fixed testsuite for environments that don't have any web browser in‐
2145 stalled. See pull request #384.
2146 Version 0.9.1
2148 released on 13 March 2016
2149 • Removed leftover debug print statement in vdirsyncer discover, see
2151 commit 3d856749f37639821b148238ef35f1acba82db36.
2152 • metasync will now strip whitespace from the start and the end of the
2154 values. See issue #358.
2155 • New Packaging Guidelines have been added to the documentation.
2157 Version 0.9.0
2159 released on 15 February 2016
2160 • The collections parameter is now required in pair configurations.
2162 Vdirsyncer will tell you what to do in its error message. See issue
2163 #328.
2164 Version 0.8.1
2166 released on 30 January 2016
2167 • Fix error messages when invalid parameter fetching strategy is used.
2169 This is important because users would receive awkward errors for us‐
2170 ing deprecated keyring fetching.
2171 Version 0.8.0
2173 released on 27 January 2016
2174 • Keyring support has been removed, which means that password.fetch =
2176 ["keyring", "example.com", "myuser"] doesn't work anymore.
2177 For existing setups: Use password.fetch = ["command", "keyring",
2179 "get", "example.com", "myuser"] instead, which is more generic. See
2180 the documentation for details.
2181 • Now emitting a warning when running under Python 2. See issue #219.
2183 Version 0.7.5
2185 released on 23 December 2015
2186 • Fixed a bug in remotestorage that would try to open a CLI browser for
2188 OAuth.
2189 • Fix a packaging bug that would prevent vdirsyncer from working with
2191 newer lxml versions.
2192 Version 0.7.4
2194 released on 22 December 2015
2195 • Improved error messages instead of faulty server behavior, see issue
2197 #290 and issue #300.
2198 • Safer shutdown of threadpool, avoid exceptions, see issue #291.
2200 • Fix a sync bug for read-only storages see commit
2202 ed22764921b2e5bf6a934cf14aa9c5fede804d8e.
2203 • Etag changes are no longer sufficient to trigger sync operations. An
2205 actual content change is also necessary. See issue #257.
2206 • remotestorage now automatically opens authentication dialogs in your
2208 configured GUI browser.
2209 • Packagers: lxml>=3.1 is now required (newer lower-bound version).
2211 Version 0.7.3
2213 released on 05 November 2015
2214 • Make remotestorage-dependencies actually optional.
2216 Version 0.7.2
2218 released on 05 November 2015
2219 • Un-break testsuite.
2221 Version 0.7.1
2223 released on 05 November 2015
2224 • Packagers: The setuptools extras keyring and remotestorage have been
2226 added. They're basically optional dependencies. See setup.py for more
2227 details.
2228 • Highly experimental remoteStorage support has been added. It may be
2230 completely overhauled or even removed in any version.
2231 • Removed mentions of old password_command in documentation.
2233 Version 0.7.0
2235 released on 27 October 2015
2236 • Packagers: New dependencies are click_threading, click_log and
2238 click>=5.0.
2239 • password_command is gone. Keyring support got completely overhauled.
2241 See keyring.
2242 Version 0.6.0
2244 released on 06 August 2015
2245 • password_command invocations with non-zero exit code are now fatal
2247 (and will abort synchronization) instead of just producing a warning.
2248 • Vdirsyncer is now able to synchronize metadata of collections. Set
2250 metadata = ["displayname"] and run vdirsyncer metasync.
2251 • Packagers: Don't use the GitHub tarballs, but the PyPI ones.
2253 • Packagers: build.sh is gone, and Makefile is included in tarballs.
2255 See the content of Makefile on how to run tests post-packaging.
2256 • verify_fingerprint doesn't automatically disable verify anymore.
2258 Version 0.5.2
2260 released on 15 June 2015
2261 • Vdirsyncer now checks and corrects the permissions of status files.
2263 • Vdirsyncer is now more robust towards changing UIDs inside items.
2265 • Vdirsyncer is now handling unicode hrefs and UIDs correctly. Software
2267 that produces non-ASCII UIDs is broken, but apparently it exists.
2268 Version 0.5.1
2270 released on 29 May 2015
2271 • N.b.: The PyPI upload of 0.5.0 is completely broken.
2273 • Raise version of required requests-toolbelt to 0.4.0.
2275 • Command line should be a lot faster when no work is done, e.g. for
2277 help output.
2278 • Fix compatibility with iCloud again.
2280 • Use only one worker if debug mode is activated.
2282 • verify=false is now disallowed in vdirsyncer, please use verify_fin‐
2284 gerprint instead.
2285 • Fixed a bug where vdirsyncer's DAV storage was not using the config‐
2287 ured useragent for collection discovery.
2288 Version 0.4.4
2290 released on 12 March 2015
2291 • Support for client certificates via the new auth_cert parameter, see
2293 issue #182 and pull request #183.
2294 • The icalendar package is no longer required.
2296 • Several bugfixes related to collection creation.
2298 Version 0.4.3
2300 released on 20 February 2015
2301 • More performance improvements to singlefile-storage.
2303 • Add post_hook param to filesystem-storage.
2305 • Collection creation now also works with SabreDAV-based servers, such
2307 as Baikal or ownCloud.
2308 • Removed some workarounds for Radicale. Upgrading to the latest Radi‐
2310 cale will fix the issues.
2311 • Fixed issues with iCloud discovery.
2313 • Vdirsyncer now includes a simple repair command that seeks to fix
2315 some broken items.
2316 Version 0.4.2
2318 released on 30 January 2015
2319 • Vdirsyncer now respects redirects when uploading and updating items.
2321 This might fix issues with Zimbra.
2322 • Relative status_path values are now interpreted as relative to the
2324 configuration file's directory.
2325 • Fixed compatibility with custom SabreDAV servers. See issue #166.
2327 • Catch harmless threading exceptions that occur when shutting down
2329 vdirsyncer. See issue #167.
2330 • Vdirsyncer now depends on atomicwrites.
2332 • Massive performance improvements to singlefile-storage.
2334 • Items with extremely long UIDs should now be saved properly in
2336 filesystem-storage. See issue #173.
2337 Version 0.4.1
2339 released on 05 January 2015
2340 • All create arguments from all storages are gone. Vdirsyncer now asks
2342 if it should try to create collections.
2343 • The old config values True, False, on, off and None are now invalid.
2345 • UID conflicts are now properly handled instead of ignoring one item.
2347 Card- and CalDAV servers are already supposed to take care of those
2348 though.
2349 • Official Baikal support added.
2351 Version 0.4.0
2353 released on 31 December 2014
2354 • The passwordeval parameter has been renamed to password_command.
2356 • The old way of writing certain config values such as lists is now
2358 gone.
2359 • Collection discovery has been rewritten. Old configuration files
2361 should be compatible with it, but vdirsyncer now caches the results
2362 of the collection discovery. You have to run vdirsyncer discover if
2363 collections were added or removed on one side.
2364 • Pair and storage names are now restricted to certain characters.
2366 Vdirsyncer will issue a clear error message if your configuration
2367 file is invalid in that regard.
2368 • Vdirsyncer now supports the XDG-Basedir specification. If the
2370 VDIRSYNCER_CONFIG environment variable isn't set and the
2371 ~/.vdirsyncer/config file doesn't exist, it will look for the config‐
2372 uration file at $XDG_CONFIG_HOME/vdirsyncer/config.
2373 • Some improvements to CardDAV and CalDAV discovery, based on problems
2375 found with FastMail. Support for .well-known-URIs has been added.
2376 Version 0.3.4
2378 released on 8 December 2014
2379 • Some more bugfixes to config handling.
2381 Version 0.3.3
2383 released on 8 December 2014
2384 • Vdirsyncer now also works with iCloud. Particularly collection dis‐
2386 covery and etag handling were fixed.
2387 • Vdirsyncer now encodes Cal- and CardDAV requests differently. This
2389 hasn't been well-tested with servers like Zimbra or SoGo, but isn't
2390 expected to cause any problems.
2391 • Vdirsyncer is now more robust regarding invalid responses from CalDAV
2393 servers. This should help with future compatibility with Davmail/Out‐
2394 look.
2395 • Fix a bug when specifying item_types of caldav in the deprecated con‐
2397 fig format.
2398 • Fix a bug where vdirsyncer would ignore all but one character speci‐
2400 fied in unsafe_href_chars of caldav and carddav.
2401 Version 0.3.2
2403 released on 3 December 2014
2404 • The current config format has been deprecated, and support for it
2406 will be removed in version 0.4.0. Vdirsyncer warns about this now.
2407 Version 0.3.1
2409 released on 24 November 2014
2410 • Fixed a bug where vdirsyncer would delete items if they're deleted on
2412 side A but modified on side B. Instead vdirsyncer will now upload the
2413 new items to side A. See issue #128.
2414 • Synchronization continues with the remaining pairs if one pair
2416 crashes, see issue #121.
2417 • The processes config key is gone. There is now a --max-workers option
2419 on the CLI which has a similar purpose. See pull request #126.
2420 • The Read The Docs-theme is no longer required for building the docs.
2422 If it is not installed, the default theme will be used. See issue
2423 #134.
2424 Version 0.3.0
2426 released on 20 September 2014
2427 • Add verify_fingerprint parameter to http, caldav and carddav, see
2429 issue #99 and pull request #106.
2430 • Add passwordeval parameter to general_config, see issue #108 and pull
2432 request #117.
2433 • Emit warnings (instead of exceptions) about certain invalid responses
2435 from the server, see issue #113. This is apparently required for
2436 compatibility with Davmail.
2437 Version 0.2.5
2439 released on 27 August 2014
2440 • Don't ask for the password of one server more than once and fix mul‐
2442 tiple concurrency issues, see issue #101.
2443 • Better validation of DAV endpoints.
2445 Version 0.2.4
2447 released on 18 August 2014
2448 • Include workaround for collection discovery with latest version of
2450 Radicale.
2451 • Include metadata files such as the changelog or license in source
2453 distribution, see issue #97 and issue #98.
2454 Version 0.2.3
2456 released on 11 August 2014
2457 • Vdirsyncer now has a --version flag, see issue #92.
2459 • Fix a lot of bugs related to special characters in URLs, see issue
2461 #49.
2462 Version 0.2.2
2464 released on 04 August 2014
2465 • Remove a security check that caused problems with special characters
2467 in DAV URLs and certain servers. On top of that, the security check
2468 was nonsensical. See issue #87 and issue #91.
2469 • Change some errors to warnings, see issue #88.
2471 • Improve collection autodiscovery for servers without full support.
2473 Version 0.2.1
2475 released on 05 July 2014
2476 • Fix bug where vdirsyncer shows empty addressbooks when using CardDAV
2478 with Zimbra.
2479 • Fix infinite loop when password doesn't exist in system keyring.
2481 • Colorized errors, warnings and debug messages.
2483 • vdirsyncer now depends on the click package instead of argvard.
2485 Version 0.2.0
2487 released on 12 June 2014
2488 • vdirsyncer now depends on the icalendar package from PyPI, to get rid
2490 of its own broken parser.
2491 • vdirsyncer now also depends on requests_toolbelt. This makes it pos‐
2493 sible to guess the authentication type instead of blankly assuming
2494 basic.
2495 • Fix a semi-bug in caldav and carddav storages where a tuple (href,
2497 etag) instead of the proper etag would have been returned from the
2498 upload method. vdirsyncer might do unnecessary copying when upgrad‐
2499 ing to this version.
2500 • Add the storage singlefile. See issue #48.
2502 • The collections parameter for pair sections now accepts the special
2504 values from a and from b for automatically discovering collections.
2505 See pair_config.
2506 • The read_only parameter was added to storage sections. See stor‐
2508 age_config.
2509 Version 0.1.5
2511 released on 14 May 2014
2512 • Introduced changelogs
2514 • Many bugfixes
2516 • Many doc fixes
2518 • vdirsyncer now doesn't necessarily need UIDs anymore for synchroniza‐
2520 tion.
2521 • vdirsyncer now aborts if one collection got completely emptied be‐
2523 tween synchronizations. See issue #42.
2524
2526 Contributors
2527 In alphabetical order:
2528 • Ben Boeckel
2530 • Christian Geier
2532 • Clément Mondon
2534 • Hugo Osvaldo Barrera
2536 • Julian Mehne
2538 • Malte Kiefer
2540 • Marek Marczykowski-Górecki
2542 • Markus Unterwaditzer
2544 • Michael Adler
2546 • Thomas Weißschuh
2548 Special thanks goes to:
2550 • FastMail sponsors a paid account for testing their servers.
2552 • Packagecloud provide repositories for vdirsyncer's Debian packages.
2554 License
2556 Copyright (c) 2014-2020 by Markus Unterwaditzer & contributors. See AU‐
2557 THORS.rst for more details.
2558 Some rights reserved.
2560 Redistribution and use in source and binary forms of the software as
2562 well as documentation, with or without modification, are permitted pro‐
2563 vided that the following conditions are met:
2564 • Redistributions of source code must retain the above copyright no‐
2566 tice, this list of conditions and the following disclaimer.
2567 • Redistributions in binary form must reproduce the above copyright no‐
2569 tice, this list of conditions and the following disclaimer in the
2570 documentation and/or other materials provided with the distribution.
2571 • The names of the contributors may not be used to endorse or promote
2573 products derived from this software without specific prior written
2574 permission.
2575 THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS
2577 AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUD‐
2578 ING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
2579 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
2580 COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, IN‐
2581 CIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
2582 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
2583 USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
2584 ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2585 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2586 OF THIS SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY
2587 OF SUCH DAMAGE.
2588
2590 If you found my work useful, please consider donating. Thank you!
2591 • Bitcoin: 16sSHxZm263WHR9P9PJjCxp64jp9ooXKVt
2593 • PayPal.me
2595 • Bountysource is useful for funding work on a specific GitHub issue.
2597 • There's also Bountysource Salt, for one-time and recurring dona‐
2599 tions.
2600 • Donations via Bountysource are publicly listed. Use PayPal if you
2602 dislike that.
2603 • Flattr or Gratipay can be used for recurring donations.
2605
2607 Markus Unterwaditzer
2608
2610 2014-2021, Markus Unterwaditzer & contributors
26110.18 Nov 11, 2021 VDIRSYNCER(1)