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

NAME

6       vdirsyncer - vdirsyncer Documentation
7
8Documentation
9
10Source code
11
12       Vdirsyncer  is  a command-line tool for synchronizing calendars and ad‐
13       dressbooks between a variety of servers and the local  filesystem.  The
14       most popular usecase is to synchronize a server with a local folder and
15       use a set of other programs to change the local  events  and  contacts.
16       Vdirsyncer can then synchronize those changes back to the server.
17
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
49Syncthing
50
51Dropbox or one of the gajillion services like it
52
53unison
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  agnostic/un‐
61         aware  of  the  files' contents. If a file has changed on both sides,
62         Dropbox just copies both versions to both sides.
63
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. DAVx⁵ 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
81ArchLinux
82
83Ubuntu  and  Debian, x86_64-only (packages also exist in the official
84         repositories but may be out of date)
85
86GNU Guix
87
88OS X (homebrew)
89
90BSD (pkgsrc)
91
92OpenBSD
93
94       We only support the latest version of vdirsyncer, which is at the  time
95       of  this  writing  0.18.0.  Please do not file bugs if you use an older
96       version.
97
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.7+ and pip.
112
113libxml and libxslt
114
115zlib
116
117       • Linux or OS X. Windows is not supported, see issue #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       pipx is a new package manager for Python-based software that  automati‐
165       cally  sets  up a virtualenv for each program you install. Assuming you
166       have it installed on your operating system, you can do:
167
168          pipx install vdirsyncer
169
170       and ~/.local/pipx/venvs/vdirsyncer will be your new vdirsyncer  instal‐
171       lation. To update vdirsyncer to the latest version:
172
173          pipx upgrade vdirsyncer
174
175       If you're done with vdirsyncer, you can do:
176
177          pipx 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 re‐
212       quired 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 au‐
259       tomatically 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  en‐
288       counters  the  situation  where  an item changed on both sides, it will
289       simply overwrite the local item with the one from the server.
290
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 ad‐
308       dressbook's or  calendar's  "human-friendly"  name  (internally  called
309       "displayname") or the color associated with a calendar. For the purpose
310       of explaining this feature, let's switch to a different  base  example.
311       This time we'll synchronize calendars:
312
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
358null:  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 be‐
390       cause your DAV-server doesn't support it, for example.  In  this  case,
391       you can set url of your carddav- or caldav-storage to a URL that points
392       to your CalDAV/CardDAV collection directly.
393
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  re‐
400       quired  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, ba‐
405       sically a foldername or a remote UUID).  When  you  have  two  servers,
406       those  collection  names may not line up as nicely. Suppose you created
407       two calendars "Test", one on a NextCloud server and one on iCloud,  us‐
408       ing their respective web interfaces. The URLs look something like this:
409
410          NextCloud: https://example.com/remote.php/dav/calendars/user/test/
411          iCloud:    https://p-XX.caldav.icloud.com/YYY/calendars/3b4c9995-5c67-4021-9fa0-be4633623e1c
412
413       Those  are two DAV calendar collections. Their collection names will be
414       test  and  3b4c9995-5c67-4021-9fa0-be4633623e1c  respectively,  so  you
415       don't  have a single name you can address them both with. You will need
416       to manually "pair" (no pun intended) those collections up like this:
417
418          [pair doublecloud]
419          a = "my_nextcloud"
420          b = "my_icloud"
421          collections = [["mytest", "test", "3b4c9995-5c67-4021-9fa0-be4633623e1c"]]
422
423       mytest gives that combination of calendars a nice name you can use when
424       talking  about  it, so you would use vdirsyncer sync doublecloud/mytest
425       to say: "Only synchronize these two storages, nothing else that may  be
426       configured".
427
428       NOTE:
429          Why not use displaynames?
430
431          You  may  wonder why vdirsyncer just couldn't figure this out by it‐
432          self. After all, you did name  both  collections  "Test"  (which  is
433          called  "the  displayname"),  so  why  not  pair collections by that
434          value?
435
436          There are a few problems with this idea:
437
438          • Two calendars may have the same exact displayname.
439
440          • A calendar may not have a (non-empty) displayname.
441
442          • The displayname might change. Either you rename the  calendar,  or
443            the calendar renames itself because you change a language setting.
444
445          In  the  end,  that  property was never designed to be parsed by ma‐
446          chines.
447

SSL AND CERTIFICATE VALIDATION

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

STORING PASSWORDS

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

SYNCING WITH READ-ONLY STORAGES

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

FULL CONFIGURATION MANUAL

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

OTHER TUTORIALS

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

KNOWN PROBLEMS

1569       For any unanswered questions or problems, see contact.
1570
1571   Requests-related ImportErrors
1572          ImportError: No module named packages.urllib3.poolmanager
1573
1574          ImportError: cannot import name iter_field_objects
1575
1576       Debian and nowadays even other distros make modifications  to  the  re‐
1577       quests package that don't play well with packages assuming a normal re‐
1578       quests. This is due to stubbornness on both sides.
1579
1580       See issue #82 and issue #140 for past discussions. You have one  option
1581       to  work  around  this, that is, to install vdirsyncer in a virtualenv,
1582       see manual-installation.
1583

CONTRIBUTING TO THIS PROJECT

1585       NOTE:
1586
1587          • Please read contact for questions and support requests.
1588
1589          • All participants must follow the pimutils Code of Conduct.
1590
1591   The issue tracker
1592       We use GitHub issues for organizing bug reports and feature requests.
1593
1594       The following labels are of interest:
1595
1596       • "Planning" is for issues that are still undecided, but where at least
1597         some discussion exists.
1598
1599       • "Blocked" is for issues that can't be worked on at the moment because
1600         some other unsolved problem exists. This problem may be a bug in some
1601         software dependency, for instance.
1602
1603       • "Ready" contains issues that are ready to work on.
1604
1605       If  you  just want to get started with contributing, the "ready" issues
1606       are an option. Issues that are still in "Planning" are also an  option,
1607       but  require more upfront thinking and may turn out to be impossible to
1608       solve, or at least harder than anticipated. On the flip side those tend
1609       to  be  the more interesting issues as well, depending on how one looks
1610       at it.
1611
1612       All of those labels are also available as a kanban board on  waffle.io.
1613       It is really just an alternative overview over all issues, but might be
1614       easier to comprehend.
1615
1616       Feel free to contact me or comment on the relevant issues  for  further
1617       information.
1618
1619   Reporting bugs
1620       • Make sure your problem isn't already listed in problems.
1621
1622       • Make  sure  you have the absolutely latest version of vdirsyncer. For
1623         users of some Linux distributions such as Debian or Fedora  this  may
1624         not  be  the  version  that your distro offers. In those cases please
1625         file  a  bug  against  the  distro  package,  not  against   upstream
1626         vdirsyncer.
1627
1628       • Use --verbosity=DEBUG when including output from vdirsyncer.
1629
1630   Suggesting features
1631       If  you're suggesting a feature, keep in mind that vdirsyncer tries not
1632       to be a full calendar or contacts client, but rather just the piece  of
1633       software  that synchronizes all the data. Take a look at the documenta‐
1634       tion for software working with vdirsyncer.
1635
1636   Submitting patches, pull requests
1637Discuss everything in the issue tracker first (or contact me  somehow
1638         else) before implementing it.
1639
1640       • Make sure the tests pass. See below for running them.
1641
1642       • But not because you wrote too few tests.
1643
1644       • Add yourself to AUTHORS.rst, and add a note to CHANGELOG.rst too.
1645
1646   Running tests, how to set up your development environment
1647       For  many  patches, it might suffice to just let CI run the tests. How‐
1648       ever, CI is slow, so you might want to run them locally too. For  this,
1649       set up a virtualenv and run this inside of it:
1650
1651          # install:
1652          #  - vdirsyncer from the repo into the virtualenv
1653          #  - stylecheckers (flake8) and code formatters (autopep8)
1654          make install-dev
1655
1656          # Install git commit hook for some extra linting and checking
1657          pre-commit install
1658
1659          # Install development dependencies
1660          make install-dev
1661
1662       Then you can run:
1663
1664          make test   # The normal testsuite
1665          make style  # Stylechecker
1666          make docs   # Build the HTML docs, output is at docs/_build/html/
1667
1668       The Makefile has a lot of options that allow you to control which tests
1669       are run, and which servers are tested. Take a look at  its  code  where
1670       they are all initialized and documented.
1671
1672       To tests against a specific DAV server, use DAV_SERVER:
1673
1674          make DAV_SERVER=xandikos test
1675
1676       The  server will be initialised in a docker container and terminated at
1677       the end of the test suite.
1678
1679       If you have any questions, feel free to open issues about it.
1680
1681   Structure of the testsuite
1682       Within tests/, there are three main folders:
1683
1684system contains system- and also integration tests. A rough rule  is:
1685         If the test is using temporary files, put it here.
1686
1687unit, where each testcase tests a single class or function.
1688
1689storage runs a generic storage testsuite against all storages.
1690
1691       The reason for this separation is: We are planning to generate separate
1692       coverage reports for each of those testsuites. Ideally unit would  gen‐
1693       erate  palatable  coverage  of  the entire codebase on its own, and the
1694       combination of system and storage as well.
1695

THE VDIR STORAGE FORMAT

1697       This document describes a standard for storing calendars  and  contacts
1698       on a filesystem, with the main goal of being easy to implement.
1699
1700       Vdirsyncer  synchronizes  to vdirs via filesystem. Each vdir (basically
1701       just a directory with some files in it) represents a  calendar  or  ad‐
1702       dressbook.
1703
1704   Basic Structure
1705       The main folder (root) contains an arbitrary number of subfolders (col‐
1706       lections), which contain only files (items). Synonyms for  "collection"
1707       may be "addressbook" or "calendar".
1708
1709       An item is:
1710
1711       • A vCard file, in which case the file extension must be .vcf, or
1712
1713       • An iCalendar file, in which case the file extension must be .ics.
1714
1715       An  item  should  contain  a UID property as described by the vCard and
1716       iCalendar standards. If it contains more than  one  UID  property,  the
1717       values of those must not differ.
1718
1719       The file must contain exactly one event, task or contact. In most cases
1720       this also implies only one VEVENT/VTODO/VCARD component per  file,  but
1721       e.g.   recurrence  exceptions  would require multiple VEVENT components
1722       per event.
1723
1724       The filename should have similar properties as the UID of the file con‐
1725       tent.   However,  there is no requirement for these two to be the same.
1726       Programs may choose to store additional metadata in that filename, how‐
1727       ever,  at the same time they must not assume that the metadata they in‐
1728       cluded will be preserved by other programs.
1729
1730   Metadata
1731       Any of the below metadata files may be absent. None of the files listed
1732       below have any file extensions.
1733
1734       • A  file  called  color  inside the vdir indicates the vdir's color, a
1735         property that is only relevant in UI design.
1736
1737         Its content is an ASCII-encoded hex-RGB value of  the  form  #RRGGBB.
1738         For  example, a file content of #FF0000 indicates that the vdir has a
1739         red (user-visible) color. No short forms or informal values  such  as
1740         red  (as  known  from  CSS, for example) are allowed. The prefixing #
1741         must be present.
1742
1743       • A file called displayname contains a UTF-8 encoded label that may  be
1744         used to represent the vdir in UIs.
1745
1746   Writing to vdirs
1747       Creating   and   modifying   items  or  metadata  files  should  happen
1748       atomically.
1749
1750       Writing to a temporary file on the same physical device, and then  mov‐
1751       ing  it  to  the appropriate location is usually a very effective solu‐
1752       tion. For this purpose, files with the extension .tmp  may  be  created
1753       inside collections.
1754
1755       When changing an item, the original filename must be used.
1756
1757   Reading from vdirs
1758       • Any  file  ending  with  the  .tmp  or  no file extension must not be
1759         treated as an item.
1760
1761       • The ident part of the filename should not be parsed  to  improve  the
1762         speed of item lookup.
1763
1764   Considerations
1765       The  primary  reason this format was chosen is due to its compatibility
1766       with the CardDAV and CalDAV standards.
1767
1768   Performance
1769       Currently, vdirs suffer from a rather major  performance  problem,  one
1770       which current implementations try to mitigate by building up indices of
1771       the collections for faster search and lookup.
1772
1773       The reason items' filenames don't contain any extra information is sim‐
1774       ple: The solutions presented induced duplication of data, where one du‐
1775       plicate might become out of date because of bad implementations. As  it
1776       stands  right  now,  an  index  format  could  be formalized separately
1777       though.
1778
1779       vdirsyncer doesn't really have to bother about efficient  item  lookup,
1780       because  its synchronization algorithm needs to fetch the whole list of
1781       items anyway.  Detecting changes is easily implemented by checking  the
1782       files' modification time.
1783

PACKAGING GUIDELINES

1785       Thank  you very much for packaging vdirsyncer! The following guidelines
1786       should help you to avoid some common pitfalls.
1787
1788       If you find yourself needing to patch anything, or going in a different
1789       direction,  please  open  an issue so we can also address in a way that
1790       works for everyone. Otherwise we get bug reports for code or  scenarios
1791       that don't exist in upstream vdirsycner.
1792
1793   Obtaining the source code
1794       The  main  distribution channel is PyPI, and source tarballs can be ob‐
1795       tained there. We mirror the same package tarball and  wheel  as  GitHub
1796       releases.  Please  do  not confuse these with the auto-generated GitHub
1797       "Source Code" tarball. Those are missing some  important  metadata  and
1798       your build will fail.
1799
1800       We give each release a tag in the git repo. If you want to get notified
1801       of new releases, GitHub's feed is a good way.
1802
1803       Tags will be signed by the maintainer who is doing the release  (start‐
1804       ing  with  0.16.8),  and generation of the tarball and wheel is done by
1805       CI. Hence, only the tag itself is signed.
1806
1807   Dependency versions
1808       As with most Python packages,  setup.py  denotes  the  dependencies  of
1809       vdirsyncer.  It  also contains lower-bound versions of each dependency.
1810       Older versions will be rejected by the testsuite.
1811
1812   Testing
1813       Everything testing-related goes through the Makefile in the root of the
1814       repository or PyPI package. Trying to e.g. run pytest directly will re‐
1815       quire a lot of environment variables to be set (for configuration)  and
1816       you probably don't want to deal with that.
1817
1818       You can install the all development dependencies with:
1819
1820          make install-dev
1821
1822       You  probably don't want this since it will use pip to download the de‐
1823       pendencies. Alternatively you can  find  the  testing  dependencies  in
1824       test-requirements.txt, again with lower-bound version requirements.
1825
1826       You  also have to have vdirsyncer fully installed at this point. Merely
1827       cd-ing into the tarball will not be sufficient.
1828
1829       Running the tests happens with:
1830
1831          make test
1832
1833       Hypothesis will randomly generate test input. If you care about  deter‐
1834       ministic tests, set the DETERMINISTIC_TESTS variable to "true":
1835
1836          make DETERMINISTIC_TESTS=true test
1837
1838       There  are  a  lot  of  additional  variables  that  allow  you to test
1839       vdirsyncer against a particular server. Those variables are  not  "sta‐
1840       ble"  and may change drastically between minor versions. Just don't use
1841       them, you are unlikely to find bugs that vdirsyncer's CI hasn't found.
1842
1843   Documentation
1844       Using Sphinx you can generate the documentation  you're  reading  right
1845       now  in  a variety of formats, such as HTML, PDF, or even as a manpage.
1846       That said, I only take care of the HTML docs' formatting.
1847
1848       You can find a list of dependencies  in  docs-requirements.txt.  Again,
1849       you can install those using pip with:
1850
1851          make install-docs
1852
1853       Then change into the docs/ directory and build whatever format you want
1854       using the Makefile in there (run make for the formats you can build).
1855
1856   Contrib files
1857       Reference systemd.service and systemd.timer unit files are provided. It
1858       is recommended to install this if your distribution is systemd-based.
1859

SUPPORT AND CONTACT

1861       • The  #pimutils  IRC channel on Libera.Chat might be active, depending
1862         on  your  timezone.  Use  it  for  support  and  general   (including
1863         off-topic) discussion.
1864
1865       • Open a GitHub issue for concrete bug reports and feature requests.
1866
1867       • Lastly,  you  can also contact the author directly. Do this for secu‐
1868         rity issues. If that doesn't work out (i.e. if I don't respond within
1869         one week), use contact@pimutils.org.
1870

CHANGELOG

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

CREDITS AND LICENSE

2526   Contributors
2527       In alphabetical order:
2528
2529       • Ben Boeckel
2530
2531       • Christian Geier
2532
2533       • Clément Mondon
2534
2535       • Hugo Osvaldo Barrera
2536
2537       • Julian Mehne
2538
2539       • Malte Kiefer
2540
2541       • Marek Marczykowski-Górecki
2542
2543       • Markus Unterwaditzer
2544
2545       • Michael Adler
2546
2547       • Thomas Weißschuh
2548
2549       Special thanks goes to:
2550
2551FastMail sponsors a paid account for testing their servers.
2552
2553Packagecloud provide repositories for vdirsyncer's Debian packages.
2554
2555   License
2556       Copyright (c) 2014-2020 by Markus Unterwaditzer & contributors. See AU‐
2557       THORS.rst for more details.
2558
2559       Some rights reserved.
2560
2561       Redistribution  and  use  in source and binary forms of the software as
2562       well as documentation, with or without modification, are permitted pro‐
2563       vided that the following conditions are met:
2564
2565       • Redistributions  of  source  code must retain the above copyright no‐
2566         tice, this list of conditions and the following disclaimer.
2567
2568       • Redistributions in binary form must reproduce the above copyright no‐
2569         tice,  this  list  of  conditions and the following disclaimer in the
2570         documentation and/or other materials provided with the distribution.
2571
2572       • The names of the contributors may not be used to endorse  or  promote
2573         products  derived  from  this software without specific prior written
2574         permission.
2575
2576       THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY  THE  COPYRIGHT  HOLDERS
2577       AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUD‐
2578       ING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY  AND
2579       FITNESS  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
2580       COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, IN‐
2581       CIDENTAL,  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
2582       NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR  SERVICES;  LOSS  OF
2583       USE,  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
2584       ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
2585       (INCLUDING  NEGLIGENCE  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
2586       OF THIS SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE  POSSIBILITY
2587       OF SUCH DAMAGE.
2588

DONATIONS

2590       If you found my work useful, please consider donating. Thank you!
2591
2592       • Bitcoin: 16sSHxZm263WHR9P9PJjCxp64jp9ooXKVt
2593
2594PayPal.me
2595
2596Bountysource is useful for funding work on a specific GitHub issue.
2597
2598         • There's  also  Bountysource  Salt, for one-time and recurring dona‐
2599           tions.
2600
2601         • Donations via Bountysource are publicly listed. Use PayPal  if  you
2602           dislike that.
2603
2604Flattr or Gratipay can be used for recurring donations.
2605

AUTHOR

2607       Markus Unterwaditzer
2608
2610       2014-2022, Markus Unterwaditzer & contributors
2611
2612
2613
2614
26150.18                             Jan 22, 2022                    VDIRSYNCER(1)
Impressum