1VDIRSYNCER(1)                     vdirsyncer                     VDIRSYNCER(1)
2
3
4

NAME

6       vdirsyncer - vdirsyncer Documentation
7
8       · Documentation
9
10       · Source code
11
12       Vdirsyncer  is  a  command-line  tool  for  synchronizing calendars and
13       addressbooks 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
18       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
22       It  aims  to  be  for  calendars  and  contacts what OfflineIMAP is for
23       emails.
24

WHEN DO I NEED VDIRSYNCER?

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
34       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
41       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
44   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
49       · Syncthing
50
51       · Dropbox or one of the gajillion services like it
52
53       · unison
54
55       · Just git with a sshd.
56
57       The  disadvantages  of those solutions largely depend on the exact file
58       sync program chosen:
59
60       · Like  with  todo.txt,  Dropbox  and  friends  are  obviously   agnos‐
61         tic/unaware  of  the  files'  contents. If a file has changed on both
62         sides, Dropbox just copies both versions to both sides.
63
64         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
69         This  point  doesn't apply to git: It has very good merging capabili‐
70         ties, better than what vdirsyncer currently has.
71
72       · 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. DAVDroid or the apps by dmfs.
75

INSTALLATION

77   OS/distro packages
78       The following packages are user-contributed and were up-to-date at  the
79       time of writing:
80
81       · ArchLinux (AUR)
82
83       · Ubuntu  and  Debian, x86_64-only (packages also exist in the official
84         repositories but may be out of date)
85
86       · GNU Guix
87
88       · OS X (homebrew)
89
90       · BSD (pkgsrc)
91
92       · OpenBSD
93
94       We only support the latest version of vdirsyncer, which is at the  time
95       of  this  writing  0.16.7.  Please do not file bugs if you use an older
96       version.
97
98       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
102       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
106   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
111       · Python 3.4+ and pip.
112
113       · libxml and libxslt
114
115       · zlib
116
117       · Linux or OS X. Windows is not supported, see :gh:`535`.
118
119       On Linux systems, using the distro's package manager is the best way to
120       do this, for example, using Ubuntu:
121
122          sudo apt-get install libxml2 libxslt1.1 zlib1g python
123
124       Then  you  have  several  options.  The following text applies for most
125       Python software by the way.
126
127   The dirty, easy way
128       The easiest way to install vdirsyncer at this point would be to run:
129
130          pip install --user --ignore-installed vdirsyncer
131
132       · --user is to install without root rights (into your home directory)
133
134       · --ignore-installed is to  work  around  Debian's  potentially  broken
135         packages (see debian-urllib3).
136
137       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
144   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
149          virtualenv ~/vdirsyncer_env
150          ~/vdirsyncer_env/bin/pip install vdirsyncer
151          alias vdirsyncer="~/vdirsyncer_env/bin/vdirsyncer
152
153       You'll have to put the last line into your .bashrc or .bash_profile.
154
155       This method has two advantages:
156
157       · 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
161       · You can delete ~/vdirsyncer_env/ to uninstall vdirsyncer entirely.
162
163   The clean, easy way
164       pipsi 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
168          pipsi install --python python3 vdirsyncer
169
170       and .local/bin/vdirsyncer will be your new vdirsyncer installation.  To
171       update vdirsyncer to the latest version:
172
173          pipsi upgrade vdirsyncer
174
175       If you're done with vdirsyncer, you can do:
176
177          pipsi uninstall vdirsyncer
178
179       and vdirsyncer will be uninstalled, including its dependencies.
180

TUTORIAL

182       Before  starting,  consider  if you actually need vdirsyncer. There are
183       better alternatives available for particular usecases.
184
185   Installation
186       See installation.
187
188   Configuration
189       NOTE:
190
191          · The config.example from the repository contains a very terse  ver‐
192            sion of this.
193
194          · 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
198          · Take  a  look  at  the problems page if anything doesn't work like
199            planned.
200
201       By default, vdirsyncer looks for its configuration file in the  follow‐
202       ing locations:
203
204       · The file pointed to by the VDIRSYNCER_CONFIG environment variable.
205
206       · ~/.vdirsyncer/config.
207
208       · $XDG_CONFIG_HOME/vdirsyncer/config,   which   is   normally   ~/.con‐
209         fig/vdirsyncer/config. See the XDG-Basedir specification.
210
211       The config file should start with a general  section,  where  the  only
212       required parameter is status_path. The following is a minimal example:
213
214          [general]
215          status_path = "~/.vdirsyncer/status/"
216
217       After the general section, an arbitrary amount of pair and storage sec‐
218       tions might come.
219
220       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
226       The following example synchronizes ownCloud's addressbooks  to  ~/.con‐
227       tacts/:
228
229          [pair my_contacts]
230          a = "my_contacts_local"
231          b = "my_contacts_remote"
232          collections = ["from a", "from b"]
233
234          [storage my_contacts_local]
235          type = "filesystem"
236          path = "~/.contacts/"
237          fileext = ".vcf"
238
239          [storage my_contacts_remote]
240          type = "carddav"
241
242          # 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
247       NOTE:
248          Configuration for other servers can be found at supported-servers.
249
250       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
258       However,  if  new  collections  are  created on the server, it will not
259       automatically start synchronizing those [2]. You need to run vdirsyncer
260       discover again to re-fetch this list instead.
261
262       [1]  You'll want to use a helper program for this.
263
264       [2]  Because  collections  are added rarely, and checking for this case
265            before every synchronization isn't worth the overhead.
266
267   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
272       1. vdirsyncer displays an error message (the default);
273
274       2. vdirsyncer chooses one alternative version over the other;
275
276       3. vdirsyncer starts a command of your choice that is supposed to merge
277          the two alternative versions.
278
279       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
283          [pair my_contacts]
284          ...
285          conflict_resolution = "b wins"
286
287       Earlier we wrote that b  =  "my_contacts_remote",  so  when  vdirsyncer
288       encounters  the  situation where an item changed on both sides, it will
289       simply overwrite the local item with the one from the server.
290
291       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
295          [pair my_contacts]
296          ...
297          conflict_resolution = ["command", "vimdiff"]
298
299       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
304       See pair_config for the reference documentation.
305
306   Metadata synchronization
307       Besides  items,  vdirsyncer  can  also  synchronize  metadata  like the
308       addressbook'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
313          [pair my_calendars]
314          a = "my_calendars_local"
315          b = "my_calendars_remote"
316          collections = ["from a", "from b"]
317          metadata = ["color"]
318
319          [storage my_calendars_local]
320          type = "filesystem"
321          path = "~/.calendars/"
322          fileext = ".ics"
323
324          [storage my_calendars_remote]
325          type = "caldav"
326
327          url = "https://owncloud.example.com/remote.php/caldav/"
328          username = "bob"
329          password = "asdf"
330
331       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
336   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
344       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
350       [3]  Which  you  can  also  synchronize  with metasync using metadata =
351            ["displayname"].
352
353            There are three collection names that have a special meaning:
354
355       · "from a", "from b": A placeholder for all  collections  that  can  be
356         found on side A/B when running vdirsyncer discover.
357
358       · null:  The  parameters  give  to the storage are exact and require no
359         discovery.
360
361       The last one requires a bit more explanation.  Assume this config which
362       synchronizes two directories of addressbooks:
363
364          [pair foobar]
365          a = "foo"
366          b = "bar"
367          collections = ["from a", "from b"]
368
369          [storage foo]
370          type = "filesystem"
371          fileext = ".vcf"
372          path = "./contacts_foo/"
373
374          [storage bar]
375          type = "filesystem"
376          fileext = ".vcf"
377          path = "./contacts_bar/"
378
379       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
384       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
389       This  is  useful  in  situations  where  listing  all collections fails
390       because 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
394       Note that not all storages support  the  null-collection,  for  example
395       google_contacts and google_calendar don't.
396
397   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
400       required  when  you  have two servers with already existing collections
401       which you want to synchronize.
402
403       The core problem in this situation is that vdirsyncer pairs collections
404       by  collection  name  by  default  (see definition in previous section,
405       basically 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,
408       using  their  respective  web  interfaces. The URLs look something like
409       this:
410
411          NextCloud: https://example.com/remote.php/dav/calendars/user/test/
412          iCloud:    https://p-XX.caldav.icloud.com/YYY/calendars/3b4c9995-5c67-4021-9fa0-be4633623e1c
413
414       Those are two DAV calendar collections. Their collection names will  be
415       test  and  3b4c9995-5c67-4021-9fa0-be4633623e1c  respectively,  so  you
416       don't have a single name you can address them both with. You will  need
417       to manually "pair" (no pun intended) those collections up like this:
418
419          [pair doublecloud]
420          a = "my_nextcloud"
421          b = "my_icloud"
422          collections = [["mytest", "test", "3b4c9995-5c67-4021-9fa0-be4633623e1c"]]
423
424       mytest gives that combination of calendars a nice name you can use when
425       talking about it, so you would use vdirsyncer  sync  doublecloud/mytest
426       to  say: "Only synchronize these two storages, nothing else that may be
427       configured".
428
429       NOTE:
430          Why not use displaynames?
431
432          You may wonder why vdirsyncer  just  couldn't  figure  this  out  by
433          itself.  After  all,  you did name both collections "Test" (which is
434          called "the displayname"), so  why  not  pair  collections  by  that
435          value?
436
437          There are a few problems with this idea:
438
439          · Two calendars may have the same exact displayname.
440
441          · A calendar may not have a (non-empty) displayname.
442
443          · The  displayname  might change. Either you rename the calendar, or
444            the calendar renames itself because you change a language setting.
445
446          In the end, that  property  was  never  designed  to  be  parsed  by
447          machines.
448

SSL AND CERTIFICATE VALIDATION

450       All SSL configuration is done per-storage.
451
452   Pinning by fingerprint
453       To pin the certificate by fingerprint:
454
455          [storage foo]
456          type = "caldav"
457          ...
458          verify_fingerprint = "94:FD:7A:CB:50:75:A4:69:82:0A:F8:23:DF:07:FC:69:3E:CD:90:CA"
459          #verify = false  # Optional: Disable CA validation, useful for self-signed certs
460
461       SHA1-,  SHA256-  or  MD5-Fingerprints  can be used. They're detected by
462       their length.
463
464       You can use the following command for obtaining a SHA-1 fingerprint:
465
466          echo -n | openssl s_client -connect unterwaditzer.net:443 | openssl x509 -noout -fingerprint
467
468       Note that verify_fingerprint doesn't suffice  for  vdirsyncer  to  work
469       with  self-signed  certificates  (or  certificates that are not in your
470       trust store). You most likely need to set verify = false as well.  This
471       disables  verification of the SSL certificate's expiration time and the
472       existence of it in your trust store, all that's  verified  now  is  the
473       fingerprint.
474
475       However,  please  consider using Let's Encrypt such that you can forget
476       about all of that. It is easier to deploy a free certificate from  them
477       than configuring all of your clients to accept the self-signed certifi‐
478       cate.
479
480   Custom root CAs
481       To point vdirsyncer to a custom set of root CAs:
482
483          [storage foo]
484          type = "caldav"
485          ...
486          verify = "/path/to/cert.pem"
487
488       Vdirsyncer uses the requests library, which, by default, uses  its  own
489       set of trusted CAs.
490
491       However, the actual behavior depends on how you have installed it. Many
492       Linux distributions patch their python-requests package to use the sys‐
493       tem  certificate  CAs. Normally these two stores are similar enough for
494       you to not care.
495
496       But there are cases where certificate validation fails even though  you
497       can  access  the  server  fine  through e.g. your browser. This usually
498       indicates that your installation of the  requests  library  is  somehow
499       broken.  In such cases, it makes sense to explicitly set verify or ver‐
500       ify_fingerprint as shown above.
501
502   Client Certificates
503       Client certificates may be specified with the auth_cert  parameter.  If
504       the  key  and  certificate  are  stored  in  the same file, it may be a
505       string:
506
507          [storage foo]
508          type = "caldav"
509          ...
510          auth_cert = "/path/to/certificate.pem"
511
512       If the key and certificate are separate, a list may be used:
513
514          [storage foo]
515          type = "caldav"
516          ...
517          auth_cert = ["/path/to/certificate.crt", "/path/to/key.key"]
518

STORING PASSWORDS

520       Changed in version 0.7.0: Password configuration got  completely  over‐
521       hauled.
522
523
524       Vdirsyncer can fetch passwords from several sources other than the con‐
525       fig file.
526
527   Command
528       Say you have the following configuration:
529
530          [storage foo]
531          type = "caldav"
532          url = ...
533          username = "foo"
534          password = "bar"
535
536       But it bugs you that the password is stored in cleartext in the  config
537       file.  You can do this:
538
539          [storage foo]
540          type = "caldav"
541          url = ...
542          username = "foo"
543          password.fetch = ["command", "~/get-password.sh", "more", "args"]
544
545       You can fetch the username as well:
546
547          [storage foo]
548          type = "caldav"
549          url = ...
550          username.fetch = ["command", "~/get-username.sh"]
551          password.fetch = ["command", "~/get-password.sh"]
552
553       Or really any kind of parameter in a storage section.
554
555       With  pass  for example, you might find yourself writing something like
556       this in your configuration file:
557
558          password.fetch = ["command", "pass", "caldav"]
559
560   Accessing the system keyring
561       As shown above, you can use the command strategy to fetch your  creden‐
562       tials  from  arbitrary  sources. A very common usecase is to fetch your
563       password from the system keyring.
564
565       The keyring Python package contains a command-line utility for fetching
566       passwords from the OS's password store. Installation:
567
568          pip install keyring
569
570       Basic usage:
571
572          password.fetch = ["command", "keyring", "get", "example.com", "foouser"]
573
574   Password Prompt
575       You can also simply prompt for the password:
576
577          [storage foo]
578          type = "caldav"
579          username = "myusername"
580          password.fetch = ["prompt", "Password for CalDAV"]
581

SYNCING WITH READ-ONLY STORAGES

583       If  you  want  to  subscribe to a public, read-only WebCAL-calendar but
584       neither your server nor your calendar apps support that (or support  it
585       insufficiently),  vdirsyncer  can  be used to synchronize such a public
586       calendar A with a new calendar B of your own and keep B updated.
587
588   Step 1: Create the target calendar
589       First you need to create the calendar you want to sync the  WebCAL-cal‐
590       endar  with. Most servers offer a web interface for this. You then need
591       to note the CalDAV URL of your calendar.  Note  that  this  URL  should
592       directly  point to the calendar you just created, which means you would
593       have one such URL for each calendar you have.
594
595   Step 2: Creating the config
596       Paste this into your vdirsyncer config:
597
598          [pair holidays]
599          a = "holidays_public"
600          b = "holidays_private"
601          collections = null
602
603          [storage holidays_public]
604          type = "http"
605          # The URL to your iCalendar file.
606          url = ...
607
608          [storage holidays_private]
609          type = "caldav"
610          # The direct URL to your calendar.
611          url = ...
612          # The credentials to your CalDAV server
613          username = ...
614          password = ...
615
616       Then run vdirsyncer discover holidays and vdirsyncer sync holidays, and
617       your previously created calendar should be filled with events.
618
619   Step 3: The partial_sync parameter
620       New in version 0.14.
621
622
623       You  may  get  into  a  situation where you want to hide or modify some
624       events from your holidays calendar. If you  try  to  do  that  at  this
625       point,  you'll  notice  that  vdirsyncer will revert any changes you've
626       made after a few times of running  sync.  This  is  because  vdirsyncer
627       wants  to  keep everything in sync, and it can't synchronize changes to
628       the public holidays-calendar because it doesn't have the rights  to  do
629       so.
630
631       For such purposes you can set the partial_sync parameter to ignore:
632
633          [pair holidays]
634          a = "holidays_public"
635          b = "holidays_private"
636          collections = null
637          partial_sync = ignore
638
639       See the config docs for more information.
640

FULL CONFIGURATION MANUAL

642       Vdirsyncer  uses  an ini-like format for storing its configuration. All
643       values are JSON, invalid JSON will get interpreted as string:
644
645          x = "foo"  # String
646          x = foo  # Shorthand for same string
647
648          x = 42  # Integer
649
650          x = ["a", "b", "c"]  # List of strings
651
652          x = true  # Boolean
653          x = false
654
655          x = null  # Also known as None
656
657   General Section
658          [general]
659          status_path = ...
660
661       · status_path: A directory where vdirsyncer will store some  additional
662         data for the next sync.
663
664         The  data is needed to determine whether a new item means it has been
665         added on one side or deleted on the other.  Relative  paths  will  be
666         interpreted as relative to the configuration file's directory.
667
668         See A simple synchronization algorithm for what exactly is in there.
669
670   Pair Section
671          [pair pair_name]
672          a = ...
673          b = ...
674          #collections = null
675          #conflict_resolution = null
676
677       · Pair  names can consist of any alphanumeric characters and the under‐
678         score.
679
680       · a and b reference the storages to sync by their names.
681
682       · collections: A list of collections  to  synchronize  when  vdirsyncer
683         sync is executed. See also collections_tutorial.
684
685         The  special  values  "from  a"  and "from b", tell vdirsyncer to try
686         autodiscovery on a specific storage.
687
688         If the collection you want to sync doesn't have the same name on each
689         side,  you may also use a value of the form ["config_name", "name_a",
690         "name_b"].  This will synchronize the collection  name_a  on  side  A
691         with  the  collection  name_b on side B. The config_name will be used
692         for representation in CLI arguments and logging.
693
694         Examples:
695
696         · collections = ["from b", "foo", "bar"] makes vdirsyncer synchronize
697           the  collections  from side B, and also the collections named "foo"
698           and "bar".
699
700         · collections = ["from b", "from a"] makes vdirsyncer synchronize all
701           existing collections on either side.
702
703         · collections  =  [["bar", "bar_a", "bar_b"], "foo"] makes vdirsyncer
704           synchronize bar_a from side A with bar_b from side B, and also syn‐
705           chronize foo on both sides with each other.
706
707       · conflict_resolution:  Optional,  define  how conflicts should be han‐
708         dled.  A conflict occurs when one item (event, task) changed on  both
709         sides since the last sync. See also conflict_resolution_tutorial.
710
711         Valid values are:
712
713         · null, where an error is shown and no changes are done.
714
715         · "a wins" and "b wins", where the whole item is taken from one side.
716
717         · ["command",  "vimdiff"]:  vimdiff  <a> <b> will be called where <a>
718           and <b> are temporary files that contain  the  item  of  each  side
719           respectively.  The  files need to be exactly the same when the com‐
720           mand returns.
721
722           · vimdiff can be replaced with any other command. For  example,  in
723             POSIX ["command", "cp"] is equivalent to "a wins".
724
725           · Additional  list  items will be forwarded as arguments. For exam‐
726             ple, ["command", "vimdiff", "--noplugin"] runs  vimdiff  --noplu‐
727             gin.
728
729         Vdirsyncer never attempts to "automatically merge" the two items.
730
731       · partial_sync: Assume A is read-only, B not. If you change items on B,
732         vdirsyncer can't sync the changes to A. What should happen instead?
733
734         · error: An error is shown.
735
736         · ignore: The change is ignored. However: Events deleted in  B  still
737           reappear if they're updated in A.
738
739         · revert (default): The change is reverted on next sync.
740
741         See also partial_sync_tutorial.
742
743       · metadata:  Metadata  keys that should be synchronized when vdirsyncer
744         metasync is executed. Example:
745
746            metadata = ["color", "displayname"]
747
748         This synchronizes the color and the displayname properties. The  con‐
749         flict_resolution parameter applies here as well.
750
751   Storage Section
752          [storage storage_name]
753          type = ...
754
755       · Storage  names  can  consist  of  any alphanumeric characters and the
756         underscore.
757
758       · type defines which kind of storage is defined.  See  Supported  Stor‐
759         ages.
760
761       · read_only  defines  whether  the  storage  should  be  regarded  as a
762         read-only storage. The value true means synchronization will  discard
763         any  changes  made  to the other side. The value false implies normal
764         2-way synchronization.
765
766       · Any further parameters are passed on to the storage class.
767
768   Supported Storages
769   CalDAV and CardDAV
770       NOTE:
771          Please also see supported-servers, as  some  servers  may  not  work
772          well.
773
774       caldav CalDAV.
775
776                 [storage example_for_caldav]
777                 type = "caldav"
778                 #start_date = null
779                 #end_date = null
780                 #item_types = []
781                 url = "..."
782                 #username = ""
783                 #password = ""
784                 #verify = true
785                 #auth = null
786                 #useragent = "vdirsyncer/0.16.4"
787                 #verify_fingerprint = null
788                 #auth_cert = null
789
790              You  can  set  a  timerange  to  synchronize with the parameters
791              start_date and end_date. Inside those parameters,  you  can  use
792              any  Python  expression  to  return  a  valid  datetime.datetime
793              object.  For  example,  the  following  would  synchronize   the
794              timerange from one year in the past to one year in the future:
795
796                 start_date = "datetime.now() - timedelta(days=365)"
797                 end_date = "datetime.now() + timedelta(days=365)"
798
799              Either both or none have to be specified. The default is to syn‐
800              chronize everything.
801
802              You can set item_types to restrict the kind of items you want to
803              synchronize. For example, if you want to only synchronize events
804              (but don't download any tasks from the server), set item_types =
805              ["VEVENT"].  If  you  want  to synchronize events and tasks, but
806              have some VJOURNAL items on the server you don't  want  to  syn‐
807              chronize, use item_types = ["VEVENT", "VTODO"].
808
809              Parameters
810
811                     · start_date  -- Start date of timerange to show, default
812                       -inf.
813
814                     · end_date -- End date  of  timerange  to  show,  default
815                       +inf.
816
817                     · item_types  --  Kind of items to show. The default, the
818                       empty list, is to show all. This depends on  particular
819                       features on the server, the results are not validated.
820
821                     · url -- Base URL or an URL to a calendar.
822
823                     · username -- Username for authentication.
824
825                     · password -- Password for authentication.
826
827                     · verify  --  Verify  SSL certificate, default True. This
828                       can also be a local path to a self-signed SSL  certifi‐
829                       cate. See ssl-tutorial for more information.
830
831                     · verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
832                       of the expected server  certificate.  See  ssl-tutorial
833                       for more information.
834
835                     · auth  --  Optional.  Either basic, digest or guess. The
836                       default is preemptive Basic auth,  sending  credentials
837                       even  if server didn't request them. This saves from an
838                       additional  roundtrip  per  request.  Consider  setting
839                       guess if this causes issues with your server.
840
841                     · auth_cert  --  Optional. Either a path to a certificate
842                       with a client certificate and the  key  or  a  list  of
843                       paths to the files with them.
844
845                     · useragent -- Default vdirsyncer.
846
847       carddav
848              CardDAV.
849
850                 [storage example_for_carddav]
851                 type = "carddav"
852                 url = "..."
853                 #username = ""
854                 #password = ""
855                 #verify = true
856                 #auth = null
857                 #useragent = "vdirsyncer/0.16.4"
858                 #verify_fingerprint = null
859                 #auth_cert = null
860
861              Parameters
862
863                     · url -- Base URL or an URL to an addressbook.
864
865                     · username -- Username for authentication.
866
867                     · password -- Password for authentication.
868
869                     · verify  --  Verify  SSL certificate, default True. This
870                       can also be a local path to a self-signed SSL  certifi‐
871                       cate. See ssl-tutorial for more information.
872
873                     · verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
874                       of the expected server  certificate.  See  ssl-tutorial
875                       for more information.
876
877                     · 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
883                     · 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
887                     · useragent -- Default vdirsyncer.
888
889   Google
890       Vdirsyncer  supports  synchronization  with  Google  calendars with the
891       restriction that VTODO files are rejected by the server.
892
893       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
898       At  first  run  you  will  be asked to authorize application for google
899       account access.
900
901       To use this storage type, you need to install some additional dependen‐
902       cies:
903
904          pip install vdirsyncer[google]
905
906       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
910       1. Go  to  the  Google  API  Manager and create a new project under any
911          name.
912
913       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
917       3. In the sidebar, select "Credentials" and create a new "OAuth  Client
918          ID". The application type is "Other".
919
920          You'll  be prompted to create a OAuth consent screen first. Fill out
921          that form however you like.
922
923       4. Finally you should have a Client ID and  a  Client  secret.  Provide
924          these in your storage config.
925
926       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
930       [googleterms]
931            See ToS, section "Confidential Matters".
932
933            NOTE:
934          You need to configure which calendars Google should offer vdirsyncer
935          using a rather hidden settings page.
936
937       google_calendar
938              Google calendar.
939
940                 [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
949              Please refer to caldav regarding the  item_types  and  timerange
950              parameters.
951
952              Parameters
953
954                     · token_file  --  A  filepath  where  access  tokens  are
955                       stored.
956
957                     · client_id/client_secret -- OAuth credentials,  obtained
958                       from the Google API Manager.
959
960       google_contacts
961              Google contacts.
962
963                 [storage example_for_google_contacts]
964                 type = "google_contacts"
965                 token_file = "..."
966                 client_id = "..."
967                 client_secret = "..."
968
969              Parameters
970
971                     · token_file  --  A  filepath  where  access  tokens  are
972                       stored.
973
974                     · client_id/client_secret -- OAuth credentials,  obtained
975                       from the Google API Manager.
976
977   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
981       To use it, you need to install some optional dependencies:
982
983          pip install vdirsyncer[etesync]
984
985       On first usage you will be prompted for the service  password  and  the
986       encryption password. Neither are stored.
987
988       etesync_contacts
989                 Contacts for etesync.
990
991                     [storage example_for_etesync_contacts]
992                     email = ...
993                     secrets_dir = ...
994                     #server_path = ...
995                     #db_path = ...
996
997              Parameters
998
999                     · email -- The email address of your account.
1000
1001                     · secrets_dir  --  A directory where vdirsyncer can store
1002                       the encryption key and authentication token.
1003
1004                     · server_url -- Optional. URL to the root of your  custom
1005                       server.
1006
1007                     · db_path -- Optional. Use a different path for the data‐
1008                       base.
1009
1010       etesync_calendars
1011              Calendars for etesync.
1012
1013                 [storage example_for_etesync_calendars]
1014                 email = ...
1015                 secrets_dir = ...
1016                 #server_path = ...
1017                 #db_path = ...
1018
1019              Parameters
1020
1021                     · email -- The email address of your account.
1022
1023                     · secrets_dir -- A directory where vdirsyncer  can  store
1024                       the encryption key and authentication token.
1025
1026                     · server_url  -- Optional. URL to the root of your custom
1027                       server.
1028
1029                     · db_path -- Optional. Use a different path for the data‐
1030                       base.
1031
1032   Local
1033       filesystem
1034              Saves each item in its own file, given a directory.
1035
1036                 [storage example_for_filesystem]
1037                 type = "filesystem"
1038                 path = "..."
1039                 fileext = "..."
1040                 #encoding = "utf-8"
1041                 #post_hook = null
1042
1043              Can be used with khal. See vdir for a more formal description of
1044              the format.
1045
1046              Directories with a leading dot are ignored to make usage of e.g.
1047              version control easier.
1048
1049              Parameters
1050
1051                     · 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
1056                     · 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).
1060
1061                     · encoding  --  File encoding for items, both content and
1062                       filename.
1063
1064                     · post_hook -- A command to call for each  item  creation
1065                       and  modification.  The command will be called with the
1066                       path of the new/updated file.
1067
1068       singlefile
1069              Save data in single local .vcf or .ics file.
1070
1071              The storage basically guesses how items should be joined in  the
1072              file.
1073
1074              New in version 0.1.6.
1075
1076
1077              NOTE:
1078                 This  storage  is  very slow, and that is unlikely to change.
1079                 You should consider using filesystem if it fits your usecase.
1080
1081              Parameters
1082
1083                     · path -- The filepath to the file to be written  to.  If
1084                       collections  are  used,  this  should  contain  %s as a
1085                       placeholder for the collection name.
1086
1087                     · encoding  --  Which  encoding  the  file  should   use.
1088                       Defaults to UTF-8.
1089
1090              Example for syncing with caldav:
1091
1092                 [pair my_calendar]
1093                 a = my_calendar_local
1094                 b = my_calendar_remote
1095                 collections = ["from a", "from b"]
1096
1097                 [storage my_calendar_local]
1098                 type = "singlefile"
1099                 path = ~/.calendars/%s.ics
1100
1101                 [storage my_calendar_remote]
1102                 type = "caldav"
1103                 url = https://caldav.example.org/
1104                 #username =
1105                 #password =
1106
1107              Example for syncing with caldav using a null collection:
1108
1109                 [pair my_calendar]
1110                 a = my_calendar_local
1111                 b = my_calendar_remote
1112
1113                 [storage my_calendar_local]
1114                 type = "singlefile"
1115                 path = ~/my_calendar.ics
1116
1117                 [storage my_calendar_remote]
1118                 type = "caldav"
1119                 url = https://caldav.example.org/username/my_calendar/
1120                 #username =
1121                 #password =
1122
1123   Read-only storages
1124       These  storages  don't  support  writing  of  their items, consequently
1125       read_only is set to true by default. Changing  read_only  to  false  on
1126       them leads to an error.
1127
1128       http   Use  a  simple  .ics  file  (or  similar)  from  the  web.  web‐
1129              cal://-calendars are supposed to be used with this, but you have
1130              to replace webcal:// with http://, or better, https://.
1131
1132                 [pair holidays]
1133                 a = holidays_local
1134                 b = holidays_remote
1135                 collections = null
1136
1137                 [storage holidays_local]
1138                 type = "filesystem"
1139                 path = ~/.config/vdir/calendars/holidays/
1140                 fileext = .ics
1141
1142                 [storage holidays_remote]
1143                 type = "http"
1144                 url = https://example.com/holidays_from_hicksville.ics
1145
1146              Too many WebCAL providers generate UIDs of all VEVENT-components
1147              on-the-fly, i.e. all UIDs change  every  time  the  calendar  is
1148              downloaded.  This leads many synchronization programs to believe
1149              that all events have been deleted  and  new  ones  created,  and
1150              accordingly causes a lot of unnecessary uploads and deletions on
1151              the other side. Vdirsyncer completely ignores UIDs  coming  from
1152              http  and  will  replace them with a hash of the normalized item
1153              content.
1154
1155              Parameters
1156
1157                     · url -- URL to the .ics file.
1158
1159                     · username -- Username for authentication.
1160
1161                     · password -- Password for authentication.
1162
1163                     · verify -- Verify SSL certificate,  default  True.  This
1164                       can  also be a local path to a self-signed SSL certifi‐
1165                       cate. See ssl-tutorial for more information.
1166
1167                     · verify_fingerprint -- Optional. SHA1 or MD5 fingerprint
1168                       of  the  expected  server certificate. See ssl-tutorial
1169                       for more information.
1170
1171                     · auth -- Optional. Either basic, digest  or  guess.  The
1172                       default  is  preemptive Basic auth, sending credentials
1173                       even if server didn't request them. This saves from  an
1174                       additional  roundtrip  per  request.  Consider  setting
1175                       guess if this causes issues with your server.
1176
1177                     · auth_cert -- Optional. Either a path to  a  certificate
1178                       with  a  client  certificate  and  the key or a list of
1179                       paths to the files with them.
1180
1181                     · useragent -- Default vdirsyncer.
1182

OTHER TUTORIALS

1184       The following section contains tutorials not explicitly about any  par‐
1185       ticular core function of vdirsyncer. They usually show how to integrate
1186       vdirsyncer with third-party software. Because of that, it may  be  that
1187       the  information regarding that other software only applies to specific
1188       versions of them.
1189
1190       NOTE:
1191          Please contribute your own tutorials  too!   Pages  are  often  only
1192          stubs and are lacking full examples.
1193
1194   Client applications
1195   Vdirsyncer with Claws Mail
1196       First  of all, Claws-Mail only supports read-only functions for vCards.
1197       It can only read contacts, but there's no editor.
1198
1199   Preparation
1200       We need to install vdirsyncer, for that look here.   Then  we  need  to
1201       create some folders:
1202
1203          mkdir ~/.vdirsyncer
1204          mkdir ~/.contacts
1205
1206   Configuration
1207       Now we create the configuration for vdirsyncer. Open ~/.vdirsyncer/con‐
1208       fig with a text editor. The config should look like this:
1209
1210          [general]
1211          status_path = "~/.vdirsyncer/status/"
1212
1213          [storage local]
1214          type = "singlefile"
1215          path = "~/.contacts/%s.vcf"
1216
1217          [storage online]
1218          type = "carddav"
1219          url = "CARDDAV_LINK"
1220          username = "USERNAME"
1221          password = "PASSWORD"
1222          read_only = true
1223
1224          [pair contacts]
1225          a = "local"
1226          b = "online"
1227          collections = ["from a", "from b"]
1228          conflict_resolution = "b wins"
1229
1230       · In the general section, we define the status folder path, for discov‐
1231         ered  collections  and  generally stuff that needs to persist between
1232         syncs.
1233
1234       · In the local section we define that all contacts should be sync in  a
1235         single file and the path for the contacts.
1236
1237       · In  the online section you must change the url, username and password
1238         to your setup. We also set the storage  to  read-only  such  that  no
1239         changes  get  synchronized  back. Claws-Mail should not be able to do
1240         any changes anyway, but this is one extra safety step in  case  files
1241         get  corrupted  or  vdirsyncer behaves eratically. You can leave that
1242         part out if you want to be able to edit those files locally.
1243
1244       · In the last section we configure that online contacts win in  a  con‐
1245         flict  situation.  Configure  this  part  however you like. A correct
1246         value depends on which side is most likely to be up-to-date.
1247
1248   Sync
1249       Now we discover and sync our contacts:
1250
1251          vdirsyncer discover contacts
1252          vdirsyncer sync contacts
1253
1254   Claws Mail
1255       Open Claws-Mail. Got to Tools => Addressbook.
1256
1257       Click on Addressbook => New vCard. Choose a name for the book.
1258
1259       Then search for the for the vCard in the folder ~/.contacts/. Click ok,
1260       and you we will see your contacts.
1261
1262       NOTE:
1263          Claws-Mail shows only contacts that have a mail address.
1264
1265   Crontab
1266       On  the end we create a crontab, so that vdirsyncer syncs automatically
1267       every 30 minutes our contacts:
1268
1269          contab -e
1270
1271       On the end of that file enter this line:
1272
1273          */30 * * * * /usr/local/bin/vdirsyncer sync > /dev/null
1274
1275       And you're done!
1276
1277   Running as a systemd.timer
1278       vdirsyncer includes unit files to run at an interval (by default  every
1279       15±5 minutes).
1280
1281       NOTE:
1282          These  are not installed when installing via pip, only via distribu‐
1283          tion packages. If  you  installed  via  pip,  or  your  distribution
1284          doesn't   ship   systemd   unit   files,  you'll  need  to  download
1285          vdirsyncer.service  and  vdirsyncer.timer  into   either   /etc/sys‐
1286          temd/user/ or ~/.local/share/systemd/user.
1287
1288   Activation
1289       To   activate   the   timer,   just   run   systemctl   --user   enable
1290       vdirsyncer.timer.  To see logs of previous runs, use journalctl  --user
1291       -u vdirsyncer.
1292
1293   Configuration
1294       It's  quite  possible that the default "every fifteen minutes" interval
1295       isn't to your liking. No default will suit everybody, but this is  con‐
1296       figurable by simply running:
1297
1298          systemctl --user edit vdirsyncer
1299
1300       This  will  open  a  blank  editor, where you can override the timer by
1301       including:
1302
1303          OnBootSec=5m  # This is how long after boot the first run takes place.
1304          OnUnitActiveSec=15m  # This is how often subsequent runs take place.
1305
1306   Todoman
1307       The  iCalendar  format  also  supports  saving   tasks   in   form   of
1308       VTODO-entries,  with  the  same  file extension as normal events: .ics.
1309       Many CalDAV servers support synchronizing tasks, vdirsyncer does too.
1310
1311       todoman is a CLI task manager supporting vdir. Its interface is similar
1312       to  the  ones  of  Taskwarrior  or  the  todo.txt  CLI app. You can use
1313       filesystem with it.
1314
1315       Further applications, with missing pages:
1316
1317       · khal, a  CLI  calendar  application  supporting  vdir.  You  can  use
1318         filesystem with it.
1319
1320       · Many  graphical calendar apps such as dayplanner, Orage or rainlendar
1321         save a calendar in a single .ics file. You can  use  singlefile  with
1322         those.
1323
1324       · khard,  a  commandline  addressbook  supporting  vdir.   You  can use
1325         filesystem with it.
1326
1327       · contactquery.c, a small program explicitly written for querying vdirs
1328         from mutt.
1329
1330       · mates, a commandline addressbook supporting vdir.
1331
1332       · vdirel, access vdir contacts from Emacs.
1333
1334   Servers
1335   Baikal
1336       Vdirsyncer is continuously tested against the latest version of Baikal.
1337
1338       · Baikal  up  to  0.2.7  also uses an old version of SabreDAV, with the
1339         same issue as ownCloud, see issue #160. This issue is fixed in  later
1340         versions.
1341
1342   DavMail (Exchange, Outlook)
1343       DavMail  is  a  proxy  program  that allows you to use Card- and CalDAV
1344       clients with Outlook. That allows you to use vdirsyncer with Outlook.
1345
1346       In practice your success with DavMail may  wildly  vary.  Depending  on
1347       your  Exchange server you might get confronted with weird errors of all
1348       sorts (including data-loss).
1349
1350       Make absolutely sure you use the latest DavMail:
1351
1352          [storage outlook]
1353          type = "caldav"
1354          url = "http://localhost:1080/users/user@example.com/calendar/"
1355          username = "user@example.com"
1356          password = ...
1357
1358       · Older versions of DavMail handle URLs case-insensitively.  See  issue
1359         #144.
1360
1361       · DavMail  is  handling  malformed  data  on  the  Exchange server very
1362         poorly. In such cases the Calendar Checking Tool  for  Outlook  might
1363         help.
1364
1365       · In some cases, you may see errors about duplicate events. It may look
1366         something like this:
1367
1368            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:
1369            error:
1370            error:     vdirsyncer repair my_calendar_remote/calendar
1371            error:
1372            error: But make sure to have a backup of your data in some form. The offending hrefs are:
1373            [...]
1374
1375         In     order     to     fix     this,     you     can     try     the
1376         Remove-DuplicateAppointments.ps1 PowerShell script that Microsoft has
1377         come up with in order to remove duplicates.
1378
1379   FastMail
1380       Vdirsyncer is continuously tested against FastMail, thanks to them  for
1381       providing  a  free  account for this purpose. There are no known issues
1382       with it.  FastMail's support pages provide the settings to use:
1383
1384          [storage cal]
1385          type = "caldav"
1386          url = "https://caldav.messagingengine.com/"
1387          username = ...
1388          password = ...
1389
1390          [storage card]
1391          type = "carddav"
1392          url = "https://carddav.messagingengine.com/"
1393          username = ...
1394          password = ...
1395
1396   Google
1397       Using vdirsyncer with Google Calendar is possible as of 0.10, but it is
1398       not tested frequently. You can use google_contacts and google_calendar.
1399
1400       For more information see issue #202 and issue #8.
1401
1402   iCloud
1403       Vdirsyncer is regularly tested against iCloud.
1404
1405          [storage cal]
1406          type = "caldav"
1407          url = "https://caldav.icloud.com/"
1408          username = ...
1409          password = ...
1410
1411          [storage card]
1412          type = "carddav"
1413          url = "https://contacts.icloud.com/"
1414          username = ...
1415          password = ...
1416
1417       Problems:
1418
1419       · Vdirsyncer  can't  do two-factor auth with iCloud (there doesn't seem
1420         to be a way to do two-factor auth over the DAV APIs) You'll  need  to
1421         use app-specific passwords instead.
1422
1423       · iCloud  has  a few special requirements when creating collections. In
1424         principle vdirsyncer can do it, but it is recommended to create  them
1425         from an Apple client (or the iCloud web interface).
1426
1427         · iCloud requires a minimum length of collection names.
1428
1429         · Calendars created by vdirsyncer cannot be used as tasklists.
1430
1431   nextCloud
1432       Vdirsyncer  is  continuously  tested  against  the  latest  version  of
1433       nextCloud:
1434
1435          [storage cal]
1436          type = "caldav"
1437          url = "https://nextcloud.example.com/"
1438          username = ...
1439          password = ...
1440
1441          [storage card]
1442          type = "carddav"
1443          url = "https://nextcloud.example.com/"
1444
1445       · WebCAL-subscriptions can't be discovered by vdirsyncer. See this rel‐
1446         evant issue.
1447
1448   ownCloud
1449       Vdirsyncer  is  continuously  tested  against  the  latest  version  of
1450       ownCloud:
1451
1452          [storage cal]
1453          type = "caldav"
1454          url = "https://example.com/remote.php/dav/"
1455          username = ...
1456          password = ...
1457
1458          [storage card]
1459          type = "carddav"
1460          url = "https://example.com/remote.php/dav/"
1461          username = ...
1462          password = ...
1463
1464       · Versions older than 7.0.0: ownCloud uses SabreDAV, which had problems
1465         detecting  collisions and race-conditions. The problems were reported
1466         and are fixed in SabreDAV's repo, and the corresponding fix  is  also
1467         in ownCloud since 7.0.0. See issue #16 for more information.
1468
1469   Radicale
1470       Radicale  is  a  very  lightweight  server,  however,  it intentionally
1471       doesn't implement the CalDAV and CardDAV  standards  completely,  which
1472       might  lead  to  issues even with very well-written clients. Apart from
1473       its non-conformity with standards, there are  multiple  other  problems
1474       with its code quality and the way it is maintained. Consider using e.g.
1475       xandikos instead.
1476
1477       That said, vdirsyncer is continuously tested against  the  git  version
1478       and the latest PyPI release of Radicale.
1479
1480       · Vdirsyncer can't create collections on Radicale.
1481
1482       · Radicale doesn't support time ranges in the calendar-query of CalDAV,
1483         so setting start_date and end_date for caldav will have no or  unpre‐
1484         dicted consequences.
1485
1486       · Versions  of  Radicale  older than 0.9b1 choke on RFC-conform queries
1487         for all items of a collection.
1488
1489         You have to set  item_types  =  ["VTODO",  "VEVENT"]  in  caldav  for
1490         vdirsyncer to work with those versions.
1491
1492   Xandikos
1493       Xandikos  is  a  lightweight,  yet  complete CalDAV and CardDAV server,
1494       backed by git. Vdirsyncer is continuously  tested  against  its  latest
1495       version.
1496
1497       After  running  ./bin/xandikos  --defaults  -d $HOME/dav, you should be
1498       able to point vdirsyncer against the root of Xandikos like this:
1499
1500          [storage cal]
1501          type = "caldav"
1502          url = "https://xandikos.example.com/"
1503          username = ...
1504          password = ...
1505
1506          [storage card]
1507          type = "carddav"
1508          url = "https://xandikos.example.com/"
1509          username = ...
1510          password = ...
1511

KNOWN PROBLEMS

1513       For any unanswered questions or problems, see contact.
1514
1515   Requests-related ImportErrors
1516          ImportError: No module named packages.urllib3.poolmanager
1517
1518          ImportError: cannot import name iter_field_objects
1519
1520       Debian and nowadays  even  other  distros  make  modifications  to  the
1521       requests  package  that don't play well with packages assuming a normal
1522       requests. This is due to stubbornness on both sides.
1523
1524       See issue #82 and issue #140 for past discussions. You have one  option
1525       to  work  around  this, that is, to install vdirsyncer in a virtualenv,
1526       see manual-installation.
1527

CONTRIBUTING TO THIS PROJECT

1529       NOTE:
1530
1531          · Please read contact for questions and support requests.
1532
1533          · All participants must follow the pimutils Code of Conduct.
1534
1535   The issue tracker
1536       We use GitHub issues for organizing bug reports and feature requests.
1537
1538       The following labels are of interest:
1539
1540       · "Planning" is for issues that are still undecided, but where at least
1541         some discussion exists.
1542
1543       · "Blocked" is for issues that can't be worked on at the moment because
1544         some other unsolved problem exists. This problem may be a bug in some
1545         software dependency, for instance.
1546
1547       · "Ready" contains issues that are ready to work on.
1548
1549       If  you  just want to get started with contributing, the "ready" issues
1550       are an option. Issues that are still in "Planning" are also an  option,
1551       but  require more upfront thinking and may turn out to be impossible to
1552       solve, or at least harder than anticipated. On the flip side those tend
1553       to  be  the more interesting issues as well, depending on how one looks
1554       at it.
1555
1556       All of those labels are also available as a kanban board on  waffle.io.
1557       It is really just an alternative overview over all issues, but might be
1558       easier to comprehend.
1559
1560       Feel free to contact me or comment on the relevant issues  for  further
1561       information.
1562
1563   Reporting bugs
1564       · Make sure your problem isn't already listed in problems.
1565
1566       · Make  sure  you have the absolutely latest version of vdirsyncer. For
1567         users of some Linux distributions such as Debian or Fedora  this  may
1568         not  be  the  version  that your distro offers. In those cases please
1569         file  a  bug  against  the  distro  package,  not  against   upstream
1570         vdirsyncer.
1571
1572       · Use --verbosity=DEBUG when including output from vdirsyncer.
1573
1574   Suggesting features
1575       If  you're suggesting a feature, keep in mind that vdirsyncer tries not
1576       to be a full calendar or contacts client, but rather just the piece  of
1577       software  that synchronizes all the data. Take a look at the documenta‐
1578       tion for software working with vdirsyncer.
1579
1580   Submitting patches, pull requests
1581       · Discuss everything in the issue tracker first (or contact me  somehow
1582         else) before implementing it.
1583
1584       · Make sure the tests pass. See below for running them.
1585
1586       · But not because you wrote too few tests.
1587
1588       · Add yourself to AUTHORS.rst, and add a note to CHANGELOG.rst too.
1589
1590   Running tests, how to set up your development environment
1591       For  many  patches,  it might suffice to just let Travis run the tests.
1592       However, Travis is slow, so you might want to run them locally too. For
1593       this, set up a virtualenv and run this inside of it:
1594
1595          # install:
1596          #  - vdirsyncer from the repo into the virtualenv
1597          #  - stylecheckers (flake8) and code formatters (autopep8)
1598          make install-dev
1599
1600          # Install git commit hook for the stylechecker
1601          make install-git-hooks
1602
1603          # install test dependencies
1604          make install-test
1605
1606       Then you can run:
1607
1608          make test   # The normal testsuite
1609          make style  # Stylechecker
1610          make docs   # Build the HTML docs, output is at docs/_build/html/
1611
1612       The Makefile has a lot of options that allow you to control which tests
1613       are run, and which servers are tested. Take a look at  its  code  where
1614       they are all initialized and documented.
1615
1616       For example, to test xandikos, run:
1617
1618          make DAV_SERVER=xandikos install-test
1619          make DAV_SERVER=xandikos test
1620
1621       If you have any questions, feel free to open issues about it.
1622
1623   Structure of the testsuite
1624       Within tests/, there are three main folders:
1625
1626       · system  contains system- and also integration tests. A rough rule is:
1627         If the test is using temporary files, put it here.
1628
1629       · unit, where each testcase tests a single class or function.
1630
1631       · storage runs a generic storage testsuite against all storages.
1632
1633       The reason for this separation is: We are planning to generate separate
1634       coverage  reports for each of those testsuites. Ideally unit would gen‐
1635       erate palatable coverage of the entire codebase on  its  own,  and  the
1636       combination of system and storage as well.
1637

THE VDIR STORAGE FORMAT

1639       This  document  describes a standard for storing calendars and contacts
1640       on a filesystem, with the main goal of being easy to implement.
1641
1642       Vdirsyncer synchronizes to vdirs via filesystem. Each  vdir  (basically
1643       just  a  directory  with  some  files  in  it) represents a calendar or
1644       addressbook.
1645
1646   Basic Structure
1647       The main folder (root) contains an arbitrary number of subfolders (col‐
1648       lections),  which contain only files (items). Synonyms for "collection"
1649       may be "addressbook" or "calendar".
1650
1651       An item is:
1652
1653       · A vCard file, in which case the file extension must be .vcf, or
1654
1655       · An iCalendar file, in which case the file extension must be .ics.
1656
1657       An item should contain a UID property as described  by  the  vCard  and
1658       iCalendar  standards.  If  it  contains more than one UID property, the
1659       values of those must not differ.
1660
1661       The file must contain exactly one event, task or contact. In most cases
1662       this  also  implies only one VEVENT/VTODO/VCARD component per file, but
1663       e.g.  recurrence exceptions would require  multiple  VEVENT  components
1664       per event.
1665
1666       The filename should have similar properties as the UID of the file con‐
1667       tent.  However, there is no requirement for these two to be  the  same.
1668       Programs may choose to store additional metadata in that filename, how‐
1669       ever, at the same time they must not  assume  that  the  metadata  they
1670       included will be preserved by other programs.
1671
1672   Metadata
1673       Any of the below metadata files may be absent. None of the files listed
1674       below have any file extensions.
1675
1676       · A file called color inside the vdir indicates  the  vdir's  color,  a
1677         property that is only relevant in UI design.
1678
1679         Its  content  is  an ASCII-encoded hex-RGB value of the form #RRGGBB.
1680         For example, a file content of #FF0000 indicates that the vdir has  a
1681         red  (user-visible)  color. No short forms or informal values such as
1682         red (as known from CSS, for example) are  allowed.  The  prefixing  #
1683         must be present.
1684
1685       · A  file called displayname contains a UTF-8 encoded label that may be
1686         used to represent the vdir in UIs.
1687
1688   Writing to vdirs
1689       Creating  and  modifying  items  or  metadata   files   should   happen
1690       atomically.
1691
1692       Writing  to a temporary file on the same physical device, and then mov‐
1693       ing it to the appropriate location is usually a  very  effective  solu‐
1694       tion.  For  this  purpose, files with the extension .tmp may be created
1695       inside collections.
1696
1697       When changing an item, the original filename must be used.
1698
1699   Reading from vdirs
1700       · Any file ending with the .tmp  or  no  file  extension  must  not  be
1701         treated as an item.
1702
1703       · The  ident  part  of the filename should not be parsed to improve the
1704         speed of item lookup.
1705
1706   Considerations
1707       The primary reason this format was chosen is due to  its  compatibility
1708       with the CardDAV and CalDAV standards.
1709
1710   Performance
1711       Currently,  vdirs  suffer  from a rather major performance problem, one
1712       which current implementations try to mitigate by building up indices of
1713       the collections for faster search and lookup.
1714
1715       The reason items' filenames don't contain any extra information is sim‐
1716       ple: The solutions presented induced duplication  of  data,  where  one
1717       duplicate  might  become out of date because of bad implementations. As
1718       it stands right now, a index  format  could  be  formalized  separately
1719       though.
1720
1721       vdirsyncer  doesn't  really have to bother about efficient item lookup,
1722       because its synchronization algorithm needs to fetch the whole list  of
1723       items  anyway.  Detecting changes is easily implemented by checking the
1724       files' modification time.
1725

PACKAGING GUIDELINES

1727       Thank you very much for packaging vdirsyncer! The following  guidelines
1728       should help you to avoid some common pitfalls.
1729
1730       While they are called guidelines and therefore theoretically not manda‐
1731       tory, if you consider going a different direction, please first open an
1732       issue or contact me otherwise instead of just going ahead. These guide‐
1733       lines exist for my own convenience too.
1734
1735   Obtaining the source code
1736       The main distribution channel is  PyPI,  and  source  tarballs  can  be
1737       obtained there. Do not use the ones from GitHub: Their tarballs contain
1738       useless junk and are more of a distraction than anything else.
1739
1740       I give each release a tag in the git repo. If you want to get  notified
1741       of new releases, GitHub's feed is a good way.
1742
1743   Dependency versions
1744       As  with  most  Python  packages,  setup.py denotes the dependencies of
1745       vdirsyncer. It also contains lower-bound versions of  each  dependency.
1746       Older versions will be rejected by the testsuite.
1747
1748   Testing
1749       Everything testing-related goes through the Makefile in the root of the
1750       repository or PyPI package. Trying to e.g. run  py.test  directly  will
1751       require  a  lot  of environment variables to be set (for configuration)
1752       and you probably don't want to deal with that.
1753
1754       You can install the testing dependencies with:
1755
1756          make install-test
1757
1758       You probably don't want this since it will  use  pip  to  download  the
1759       dependencies.  Alternatively  you  can find the testing dependencies in
1760       test-requirements.txt, again with lower-bound version requirements.
1761
1762       You also have to have vdirsyncer fully installed at this point.  Merely
1763       cd-ing into the tarball will not be sufficient.
1764
1765       Running the tests happens with:
1766
1767          make test
1768
1769       Hypothesis  will randomly generate test input. If you care about deter‐
1770       ministic tests, set the DETERMINISTIC_TESTS variable to "true":
1771
1772          make DETERMINISTIC_TESTS=true test
1773
1774       There are a  lot  of  additional  variables  that  allow  you  to  test
1775       vdirsyncer  against  a particular server. Those variables are not "sta‐
1776       ble" and may change drastically between minor versions. Just don't  use
1777       them, you are unlikely to find bugs that vdirsyncer's CI hasn't found.
1778
1779   Documentation
1780       Using  Sphinx  you  can generate the documentation you're reading right
1781       now in a variety of formats, such as HTML, PDF, or even as  a  manpage.
1782       That said, I only take care of the HTML docs' formatting.
1783
1784       You  can  find  a list of dependencies in docs-requirements.txt. Again,
1785       you can install those using pip with:
1786
1787          make install-docs
1788
1789       Then change into the docs/ directory and build whatever format you want
1790       using the Makefile in there (run make for the formats you can build).
1791
1792   Contrib files
1793       Reference systemd.service and systemd.timer unit files are provided. It
1794       is recommended to install this if your distribution is systemd-based.
1795

SUPPORT AND CONTACT

1797       · The #pimutils IRC channel on Freenode might be active,  depending  on
1798         your  timezone.  Use it for support and general (including off-topic)
1799         discussion.
1800
1801       · Open a GitHub issue for concrete bug reports and feature requests.
1802
1803       · Lastly, you can also contact the author directly. Do this  for  secu‐
1804         rity issues. If that doesn't work out (i.e. if I don't respond within
1805         one week), use contact@pimutils.org.
1806

CHANGELOG

1808       This changelog only contains information that might be  useful  to  end
1809       users  and  package  maintainers.  For further info, see the git commit
1810       log.
1811
1812       Package maintainers and users who have to manually update their instal‐
1813       lation may want to subscribe to GitHub's tag feed.
1814
1815   Version 0.16.7
1816       released on July 19
1817
1818       · Fixes for Python 3.7
1819
1820   Version 0.16.6
1821       released on 13 June 2018
1822
1823       · Packagers: Documentation building no longer needs a working installa‐
1824         tion of vdirsyncer.
1825
1826   Version 0.16.5
1827       released on 13 June 2018
1828
1829       · Packagers: click-log 0.3 is required.
1830
1831       · All output will now happen on  stderr  (because  of  the  upgrade  of
1832         click-log).
1833
1834   Version 0.16.4
1835       released on 05 February 2018
1836
1837       · Fix  tests  for  new  Hypothesis  version. (Literally no other change
1838         included)
1839
1840   Version 0.16.3
1841       released on 03 October 2017
1842
1843       · First version with custom Debian and Ubuntu packages. See issue #663.
1844
1845       · Remove invalid ASCII control characters from  server  responses.  See
1846         issue #626.
1847
1848       · packagers: Python 3.3 is no longer supported. See pull request #674.
1849
1850   Version 0.16.2
1851       released on 24 August 2017
1852
1853       · Fix  crash when using daterange or item_type filters in google_calen‐
1854         dar, see issue #657.
1855
1856       · Packagers: Fixes for new version  0.2.0  of  click-log.  The  version
1857         requirements for the dependency click-log changed.
1858
1859   Version 0.16.1
1860       released on 8 August 2017
1861
1862       · Removed remoteStorage support, see issue #647.
1863
1864       · Fixed  test  failures  caused  by  latest requests version, see issue
1865         #660.
1866
1867   Version 0.16.0
1868       released on 2 June 2017
1869
1870       · Strip METHOD:PUBLISH added by  some  calendar  providers,  see  issue
1871         #502.
1872
1873       · Fix crash of Google storages when saving token file.
1874
1875       · Make DAV discovery more RFC-conformant, see pull request #585.
1876
1877       · Vdirsyncer is now tested against Xandikos, see pull request #601.
1878
1879       · Subfolders  with  a  leading  dot are now ignored during discover for
1880         filesystem storage. This makes it easier to combine it  with  version
1881         control.
1882
1883       · Statuses  are  now stored in a sqlite database. Old data is automati‐
1884         cally migrated. Users with really  large  datasets  should  encounter
1885         performance improvements. This means that sqlite3 is now a dependency
1886         of vdirsyncer.
1887
1888       · Vdirsyncer is now licensed under the 3-clause BSD license, see  issue
1889         #610.
1890
1891       · Vdirsyncer  now  includes  experimental support for EteSync, see pull
1892         request #614.
1893
1894       · Vdirsyncer now uses more filesystem metadata for determining  whether
1895         an item changed. You will notice a possibly heavy CPU/IO spike on the
1896         first sync after upgrading.
1897
1898       · Packagers: Reference systemd.service and systemd.timer unit files are
1899         provided. It is recommended to install these as documentation if your
1900         distribution is systemd-based.
1901
1902   Version 0.15.0
1903       released on 28 February 2017
1904
1905       · Deprecated  syntax  for  configuration  values  is   now   completely
1906         rejected. All values now have to be valid JSON.
1907
1908       · A  few  UX improvements for Google storages, see issue #549 and issue
1909         #552.
1910
1911       · Fix collection discovery for google_contacts, see issue #564.
1912
1913       · iCloud is now tested on Travis, see issue #567.
1914
1915   Version 0.14.1
1916       released on 05 January 2017
1917
1918       · vdirsyncer repair no longer changes  "unsafe"  UIDs  by  default,  an
1919         extra option has to be specified. See issue #527.
1920
1921       · A lot of important documentation updates.
1922
1923   Version 0.14.0
1924       released on 26 October 2016
1925
1926       · vdirsyncer  sync  now  continues  other uploads if one upload failed.
1927         The exit code in such situations is still non-zero.
1928
1929       · Add partial_sync option to pair section. See the config docs.
1930
1931       · Vdirsyner will now warn if there's a string without  quotes  in  your
1932         config.   Please  file  issues  if  you  find documentation that uses
1933         unquoted strings.
1934
1935       · Fix an issue that would break khal's config setup wizard.
1936
1937   Version 0.13.1
1938       released on 30 September 2016
1939
1940       · Fix a bug that would completely break collection discovery.
1941
1942   Version 0.13.0
1943       released on 29 September 2016
1944
1945       · Python 2 is no longer supported at all. See issue #219.
1946
1947       · Config sections are now checked for duplicate names. This also  means
1948         that you cannot have a storage section [storage foo] and a pair [pair
1949         foo] in your config, they have to have different names. This is  done
1950         such that console output is always unambiguous. See issue #459.
1951
1952       · Custom  commands can now be used for conflict resolution during sync.
1953         See issue #127.
1954
1955       · http now completely ignores UIDs. This avoids a  lot  of  unnecessary
1956         down- and uploads.
1957
1958   Version 0.12.1
1959       released on 20 August 2016
1960
1961       · Fix a crash for Google and DAV storages. See pull request #492.
1962
1963       · Fix an URL-encoding problem with DavMail. See issue #491.
1964
1965   Version 0.12
1966       released on 19 August 2016
1967
1968       · singlefile now supports collections. See pull request #488.
1969
1970   Version 0.11.3
1971       released on 29 July 2016
1972
1973       · Default  value  of  auth parameter was changed from guess to basic to
1974         resolve issues with  the  Apple  Calendar  Server  (issue  #457)  and
1975         improve performance. See issue #461.
1976
1977       · Packagers:  The  click-threading  requirement  is  now  >=0.2. It was
1978         incorrect before. See issue #478.
1979
1980       · Fix a bug in the DAV XML parsing  code  that  would  make  vdirsyncer
1981         crash on certain input. See issue #480.
1982
1983       · Redirect  chains  should  now  be  properly  handled  when  resolving
1984         well-known URLs. See pull request #481.
1985
1986   Version 0.11.2
1987       released on 15 June 2016
1988
1989       · Fix typo that would break tests.
1990
1991   Version 0.11.1
1992       released on 15 June 2016
1993
1994       · Fix a bug in collection validation.
1995
1996       · Fix a cosmetic bug in debug output.
1997
1998       · Various documentation improvements.
1999
2000   Version 0.11.0
2001       released on 19 May 2016
2002
2003       · Discovery is no longer automatically  done  when  running  vdirsyncer
2004         sync.  vdirsyncer discover now has to be explicitly called.
2005
2006       · Add a .plist example for Mac OS X.
2007
2008       · Usage  under  Python  2 now requires a special config parameter to be
2009         set.
2010
2011       · Various deprecated configuration parameters do no  longer  have  spe‐
2012         cialized errormessages. The generic error message for unknown parame‐
2013         ters is shown.
2014
2015         · Vdirsyncer no longer warns that the passwordeval parameter has been
2016           renamed to password_command.
2017
2018         · The  keyring  fetching strategy has been dropped some versions ago,
2019           but the specialized error message has been dropped.
2020
2021         · An old status format from version 0.4 is no  longer  supported.  If
2022           you're experiencing problems, just delete your status folder.
2023
2024   Version 0.10.0
2025       released on 23 April 2016
2026
2027       · New  storage  types  google_calendar  and  google_contacts  have been
2028         added.
2029
2030       · New global command line option --config, to  specify  an  alternative
2031         config file. See issue #409.
2032
2033       · The  collections  parameter  can  now  be used to synchronize differ‐
2034         ently-named collections with each other.
2035
2036       · Packagers: The lxml dependency has been dropped.
2037
2038       · XML parsing is now a lot stricter. Malfunctioning servers  that  used
2039         to work with vdirsyncer may stop working.
2040
2041   Version 0.9.3
2042       released on 22 March 2016
2043
2044       · singlefile and http now handle recurring events properly.
2045
2046       · Fix a typo in the packaging guidelines.
2047
2048       · Moved  to pimutils organization on GitHub. Old links should redirect,
2049         but be aware of client software that doesn't  properly  handle  redi‐
2050         rects.
2051
2052   Version 0.9.2
2053       released on 13 March 2016
2054
2055       · Fixed  testsuite  for  environments  that  don't have any web browser
2056         installed.  See pull request #384.
2057
2058   Version 0.9.1
2059       released on 13 March 2016
2060
2061       · Removed leftover debug print statement in  vdirsyncer  discover,  see
2062         commit 3d856749f37639821b148238ef35f1acba82db36.
2063
2064       · metasync  will now strip whitespace from the start and the end of the
2065         values. See issue #358.
2066
2067       · New Packaging Guidelines have been added to the documentation.
2068
2069   Version 0.9.0
2070       released on 15 February 2016
2071
2072       · The collections parameter is now  required  in  pair  configurations.
2073         Vdirsyncer  will  tell you what to do in its error message. See issue
2074         #328.
2075
2076   Version 0.8.1
2077       released on 30 January 2016
2078
2079       · Fix error messages when invalid parameter fetching strategy is  used.
2080         This  is  important  because  users  would receive awkward errors for
2081         using deprecated keyring fetching.
2082
2083   Version 0.8.0
2084       released on 27 January 2016
2085
2086       · Keyring support has been removed, which means that  password.fetch  =
2087         ["keyring", "example.com", "myuser"] doesn't work anymore.
2088
2089         For  existing  setups:  Use  password.fetch  = ["command", "keyring",
2090         "get", "example.com", "myuser"] instead, which is more  generic.  See
2091         the documentation for details.
2092
2093       · Now emitting a warning when running under Python 2. See issue #219.
2094
2095   Version 0.7.5
2096       released on 23 December 2015
2097
2098       · Fixed a bug in remotestorage that would try to open a CLI browser for
2099         OAuth.
2100
2101       · Fix a packaging bug that would prevent vdirsyncer from  working  with
2102         newer lxml versions.
2103
2104   Version 0.7.4
2105       released on 22 December 2015
2106
2107       · Improved  error messages instead of faulty server behavior, see issue
2108         #290 and issue #300.
2109
2110       · Safer shutdown of threadpool, avoid exceptions, see issue #291.
2111
2112       · Fix   a   sync   bug    for    read-only    storages    see    commit
2113         ed22764921b2e5bf6a934cf14aa9c5fede804d8e.
2114
2115       · Etag  changes are no longer sufficient to trigger sync operations. An
2116         actual content change is also necessary. See issue #257.
2117
2118       · remotestorage now automatically opens authentication dialogs in  your
2119         configured GUI browser.
2120
2121       · Packagers: lxml>=3.1 is now required (newer lower-bound version).
2122
2123   Version 0.7.3
2124       released on 05 November 2015
2125
2126       · Make remotestorage-dependencies actually optional.
2127
2128   Version 0.7.2
2129       released on 05 November 2015
2130
2131       · Un-break testsuite.
2132
2133   Version 0.7.1
2134       released on 05 November 2015
2135
2136       · Packagers:  The setuptools extras keyring and remotestorage have been
2137         added. They're basically optional dependencies. See setup.py for more
2138         details.
2139
2140       · Highly  experimental  remoteStorage support has been added. It may be
2141         completely overhauled or even removed in any version.
2142
2143       · Removed mentions of old password_command in documentation.
2144
2145   Version 0.7.0
2146       released on 27 October 2015
2147
2148       · Packagers:  New  dependencies  are  click_threading,  click_log   and
2149         click>=5.0.
2150
2151       · password_command  is gone. Keyring support got completely overhauled.
2152         See keyring.
2153
2154   Version 0.6.0
2155       released on 06 August 2015
2156
2157       · password_command invocations with non-zero exit code  are  now  fatal
2158         (and will abort synchronization) instead of just producing a warning.
2159
2160       · Vdirsyncer  is  now  able to synchronize metadata of collections. Set
2161         metadata = ["displayname"] and run vdirsyncer metasync.
2162
2163       · Packagers: Don't use the GitHub tarballs, but the PyPI ones.
2164
2165       · Packagers: build.sh is gone, and Makefile is  included  in  tarballs.
2166         See the content of Makefile on how to run tests post-packaging.
2167
2168       · verify_fingerprint doesn't automatically disable verify anymore.
2169
2170   Version 0.5.2
2171       released on 15 June 2015
2172
2173       · Vdirsyncer now checks and corrects the permissions of status files.
2174
2175       · Vdirsyncer is now more robust towards changing UIDs inside items.
2176
2177       · Vdirsyncer is now handling unicode hrefs and UIDs correctly. Software
2178         that produces non-ASCII UIDs is broken, but apparently it exists.
2179
2180   Version 0.5.1
2181       released on 29 May 2015
2182
2183       · N.b.: The PyPI upload of 0.5.0 is completely broken.
2184
2185       · Raise version of required requests-toolbelt to 0.4.0.
2186
2187       · Command line should be a lot faster when no work is  done,  e.g.  for
2188         help output.
2189
2190       · Fix compatibility with iCloud again.
2191
2192       · Use only one worker if debug mode is activated.
2193
2194       · verify=false  is now disallowed in vdirsyncer, please use verify_fin‐
2195         gerprint instead.
2196
2197       · Fixed a bug where vdirsyncer's DAV storage was not using the  config‐
2198         ured useragent for collection discovery.
2199
2200   Version 0.4.4
2201       released on 12 March 2015
2202
2203       · Support  for client certificates via the new auth_cert parameter, see
2204         issue #182 and pull request #183.
2205
2206       · The icalendar package is no longer required.
2207
2208       · Several bugfixes related to collection creation.
2209
2210   Version 0.4.3
2211       released on 20 February 2015
2212
2213       · More performance improvements to singlefile-storage.
2214
2215       · Add post_hook param to filesystem-storage.
2216
2217       · Collection creation now also works with SabreDAV-based servers,  such
2218         as Baikal or ownCloud.
2219
2220       · Removed  some workarounds for Radicale. Upgrading to the latest Radi‐
2221         cale will fix the issues.
2222
2223       · Fixed issues with iCloud discovery.
2224
2225       · Vdirsyncer now includes a simple repair command  that  seeks  to  fix
2226         some broken items.
2227
2228   Version 0.4.2
2229       released on 30 January 2015
2230
2231       · Vdirsyncer  now respects redirects when uploading and updating items.
2232         This might fix issues with Zimbra.
2233
2234       · Relative status_path values are now interpreted as  relative  to  the
2235         configuration file's directory.
2236
2237       · Fixed compatibility with custom SabreDAV servers. See issue #166.
2238
2239       · Catch  harmless  threading  exceptions  that occur when shutting down
2240         vdirsyncer.  See issue #167.
2241
2242       · Vdirsyncer now depends on atomicwrites.
2243
2244       · Massive performance improvements to singlefile-storage.
2245
2246       · Items with extremely long  UIDs  should  now  be  saved  properly  in
2247         filesystem-storage. See issue #173.
2248
2249   Version 0.4.1
2250       released on 05 January 2015
2251
2252       · All  create arguments from all storages are gone. Vdirsyncer now asks
2253         if it should try to create collections.
2254
2255       · The old config values True, False, on, off and None are now invalid.
2256
2257       · UID conflicts are now properly handled instead of ignoring one  item.
2258         Card-  and  CalDAV servers are already supposed to take care of those
2259         though.
2260
2261       · Official Baikal support added.
2262
2263   Version 0.4.0
2264       released on 31 December 2014
2265
2266       · The passwordeval parameter has been renamed to password_command.
2267
2268       · The old way of writing certain config values such  as  lists  is  now
2269         gone.
2270
2271       · Collection  discovery  has  been  rewritten.  Old configuration files
2272         should be compatible with it, but vdirsyncer now caches  the  results
2273         of  the  collection discovery. You have to run vdirsyncer discover if
2274         collections were added or removed on one side.
2275
2276       · Pair and storage names are  now  restricted  to  certain  characters.
2277         Vdirsyncer  will  issue  a  clear error message if your configuration
2278         file is invalid in that regard.
2279
2280       · Vdirsyncer  now  supports  the  XDG-Basedir  specification.  If   the
2281         VDIRSYNCER_CONFIG    environment   variable   isn't   set   and   the
2282         ~/.vdirsyncer/config file doesn't exist, it will look for the config‐
2283         uration file at $XDG_CONFIG_HOME/vdirsyncer/config.
2284
2285       · Some  improvements to CardDAV and CalDAV discovery, based on problems
2286         found with FastMail. Support for .well-known-URIs has been added.
2287
2288   Version 0.3.4
2289       released on 8 December 2014
2290
2291       · Some more bugfixes to config handling.
2292
2293   Version 0.3.3
2294       released on 8 December 2014
2295
2296       · Vdirsyncer now also works with iCloud. Particularly  collection  dis‐
2297         covery and etag handling were fixed.
2298
2299       · Vdirsyncer  now  encodes  Cal- and CardDAV requests differently. This
2300         hasn't been well-tested with servers like Zimbra or SoGo,  but  isn't
2301         expected to cause any problems.
2302
2303       · Vdirsyncer is now more robust regarding invalid responses from CalDAV
2304         servers. This should help with future compatibility with Davmail/Out‐
2305         look.
2306
2307       · Fix a bug when specifying item_types of caldav in the deprecated con‐
2308         fig format.
2309
2310       · Fix a bug where vdirsyncer would ignore all but one character  speci‐
2311         fied in unsafe_href_chars of caldav and carddav.
2312
2313   Version 0.3.2
2314       released on 3 December 2014
2315
2316       · The  current  config  format  has been deprecated, and support for it
2317         will be removed in version 0.4.0. Vdirsyncer warns about this now.
2318
2319   Version 0.3.1
2320       released on 24 November 2014
2321
2322       · Fixed a bug where vdirsyncer would delete items if they're deleted on
2323         side A but modified on side B. Instead vdirsyncer will now upload the
2324         new items to side A. See issue #128.
2325
2326       · Synchronization continues  with  the  remaining  pairs  if  one  pair
2327         crashes, see issue #121.
2328
2329       · The processes config key is gone. There is now a --max-workers option
2330         on the CLI which has a similar purpose. See pull request #126.
2331
2332       · The Read The Docs-theme is no longer required for building the  docs.
2333         If  it  is  not  installed, the default theme will be used. See issue
2334         #134.
2335
2336   Version 0.3.0
2337       released on 20 September 2014
2338
2339       · Add verify_fingerprint parameter to http,  caldav  and  carddav,  see
2340         issue #99 and pull request #106.
2341
2342       · Add passwordeval parameter to general_config, see issue #108 and pull
2343         request #117.
2344
2345       · Emit warnings (instead of exceptions) about certain invalid responses
2346         from  the  server,  see  issue #113.  This is apparently required for
2347         compatibility with Davmail.
2348
2349   Version 0.2.5
2350       released on 27 August 2014
2351
2352       · Don't ask for the password of one server more than once and fix  mul‐
2353         tiple concurrency issues, see issue #101.
2354
2355       · Better validation of DAV endpoints.
2356
2357   Version 0.2.4
2358       released on 18 August 2014
2359
2360       · Include  workaround  for  collection discovery with latest version of
2361         Radicale.
2362
2363       · Include metadata files such as the changelog  or  license  in  source
2364         distribution, see issue #97 and issue #98.
2365
2366   Version 0.2.3
2367       released on 11 August 2014
2368
2369       · Vdirsyncer now has a --version flag, see issue #92.
2370
2371       · Fix  a  lot  of bugs related to special characters in URLs, see issue
2372         #49.
2373
2374   Version 0.2.2
2375       released on 04 August 2014
2376
2377       · Remove a security check that caused problems with special  characters
2378         in  DAV  URLs and certain servers. On top of that, the security check
2379         was nonsensical.  See issue #87 and issue #91.
2380
2381       · Change some errors to warnings, see issue #88.
2382
2383       · Improve collection autodiscovery for servers without full support.
2384
2385   Version 0.2.1
2386       released on 05 July 2014
2387
2388       · Fix bug where vdirsyncer shows empty addressbooks when using  CardDAV
2389         with Zimbra.
2390
2391       · Fix infinite loop when password doesn't exist in system keyring.
2392
2393       · Colorized errors, warnings and debug messages.
2394
2395       · vdirsyncer now depends on the click package instead of argvard.
2396
2397   Version 0.2.0
2398       released on 12 June 2014
2399
2400       · vdirsyncer now depends on the icalendar package from PyPI, to get rid
2401         of its own broken parser.
2402
2403       · vdirsyncer now also depends on requests_toolbelt. This makes it  pos‐
2404         sible  to  guess  the authentication type instead of blankly assuming
2405         basic.
2406
2407       · Fix a semi-bug in caldav and carddav storages where  a  tuple  (href,
2408         etag)  instead  of  the proper etag would have been returned from the
2409         upload method.  vdirsyncer might do unnecessary copying when  upgrad‐
2410         ing to this version.
2411
2412       · Add the storage singlefile. See issue #48.
2413
2414       · The  collections  parameter for pair sections now accepts the special
2415         values from a and from b for automatically  discovering  collections.
2416         See pair_config.
2417
2418       · The  read_only  parameter  was  added  to storage sections. See stor‐
2419         age_config.
2420
2421   Version 0.1.5
2422       released on 14 May 2014
2423
2424       · Introduced changelogs
2425
2426       · Many bugfixes
2427
2428       · Many doc fixes
2429
2430       · vdirsyncer now doesn't necessarily need UIDs anymore for synchroniza‐
2431         tion.
2432
2433       · vdirsyncer  now  aborts  if  one  collection  got  completely emptied
2434         between synchronizations. See issue #42.
2435

CREDITS AND LICENSE

2437   Contributors
2438       In alphabetical order:
2439
2440       · Ben Boeckel
2441
2442       · Christian Geier
2443
2444       · Clément Mondon
2445
2446       · Hugo Osvaldo Barrera
2447
2448       · Julian Mehne
2449
2450       · Malte Kiefer
2451
2452       · Marek Marczykowski-Górecki
2453
2454       · Markus Unterwaditzer
2455
2456       · Michael Adler
2457
2458       · Thomas Weißschuh
2459
2460       Additionally FastMail sponsored a paid account for testing. Thanks!
2461
2462   License
2463       Copyright (c) 2014-2016 by Markus  Unterwaditzer  &  contributors.  See
2464       AUTHORS.rst for more details.
2465
2466       Some rights reserved.
2467
2468       Redistribution  and  use  in source and binary forms of the software as
2469       well as documentation, with or without modification, are permitted pro‐
2470       vided that the following conditions are met:
2471
2472       · Redistributions  of  source  code  must  retain  the  above copyright
2473         notice, this list of conditions and the following disclaimer.
2474
2475       · Redistributions in binary form must  reproduce  the  above  copyright
2476         notice,  this  list of conditions and the following disclaimer in the
2477         documentation and/or other materials provided with the distribution.
2478
2479       · The names of the contributors may not be used to endorse  or  promote
2480         products  derived  from  this software without specific prior written
2481         permission.
2482
2483       THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY  THE  COPYRIGHT  HOLDERS
2484       AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUD‐
2485       ING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY  AND
2486       FITNESS  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
2487       COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE  FOR  ANY  DIRECT,  INDIRECT,
2488       INCIDENTAL,  SPECIAL,  EXEMPLARY,  OR CONSEQUENTIAL DAMAGES (INCLUDING,
2489       BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES;  LOSS
2490       OF  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
2491       ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT  LIABILITY,  OR
2492       TORT  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
2493       USE OF THIS SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF  THE  POSSI‐
2494       BILITY OF SUCH DAMAGE.
2495

DONATIONS

2497       If you found my work useful, please consider donating. Thank you!
2498
2499       · Bitcoin: 16sSHxZm263WHR9P9PJjCxp64jp9ooXKVt
2500
2501       · PayPal.me
2502
2503       · Bountysource is useful for funding work on a specific GitHub issue.
2504
2505         · There's  also  Bountysource  Salt, for one-time and recurring dona‐
2506           tions.
2507
2508         · Donations via Bountysource are publicly listed. Use PayPal  if  you
2509           dislike that.
2510
2511       · Flattr or Gratipay can be used for recurring donations.
2512

AUTHOR

2514       Markus Unterwaditzer
2515
2517       2014-2019, Markus Unterwaditzer & contributors
2518
2519
2520
2521
25220.16                             Nov 15, 2019                    VDIRSYNCER(1)
Impressum