diff --git a/docs/index.rst b/docs/index.rst index e914066..82aec79 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -20,6 +20,7 @@ Table of Contents .. toctree:: :maxdepth: 1 + when tutorial ssl-tutorial keyring diff --git a/docs/supported.rst b/docs/supported.rst index 931cbfb..c01757d 100644 --- a/docs/supported.rst +++ b/docs/supported.rst @@ -98,6 +98,9 @@ latest PyPI release of Radicale_. .. _Radicale: http://radicale.org/ + +.. _owncloud_setup: + ownCloud -------- @@ -132,6 +135,8 @@ the settings to use:: .. _FastMail: https://www.fastmail.com/ +.. _icloud_setup: + iCloud ------ @@ -158,6 +163,8 @@ Problems: .. _iCloud: https://www.icloud.com/ +.. _davmail_setup: + DavMail (Exchange, Outlook) --------------------------- diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 1492bb2..b8beb76 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -2,6 +2,9 @@ Tutorial ======== +Before starting, :doc:`consider if you actually need vdirsyncer `. There +are better alternatives available for particular usecases. + Installation ============ @@ -93,6 +96,8 @@ further reference, it uses the storages More Configuration ================== +.. _conflict_resolution: + Conflict resolution ------------------- diff --git a/docs/when.rst b/docs/when.rst new file mode 100644 index 0000000..31e17e7 --- /dev/null +++ b/docs/when.rst @@ -0,0 +1,72 @@ +========================== +When do I need Vdirsyncer? +========================== + +*TL;DR: Only if you want to sync with a smartphone.* + +Why not Dropbox? (or anything like it) +====================================== + +Since vdirs are just a bunch of files, it is obvious to try *file +synchronization* for synchronizing your data between multiple computers, such +as: + +* `Syncthing `_ +* `Dropbox `_ or one of the gajillion services like it +* `unison `_ + +If you only need to synchronize things between several desktop machines (and +not e.g. smartphones), using any of those to sync your vdirs will probably fit +your usecase. + +**However**, be aware that none of those services are capable of solving +synchronization conflicts properly if you have all of your data in a single +file. Projects like `todo.txt `_ get bitten by this +because they have all data in a single file: This means that if you change +*anything in your task list on two devices*, you have to merge those lists +manually. At least this is the case with Dropbox, which will create two +``todo.txt`` files in such situations. + +Why not git? +============ + +If file synchronization software is so dumb about sync conflicts, why not use +git then? Why not put your vdirs into a repo, and just ``git commit``, ``git +push`` and ``git pull``? It has **many advantages over both Vdirsyncer and +Dropbox**: + +* **Full change history:** If some stupid software deletes all your data, just + revert the commit! + +* **Better at merging in-file conflicts (sometimes):** If you changed the + summary of a task on one computer and the due date on another one, git might + be able to merge these two files to have the new summary *and* the new due + date. + + Vdirsyncer is currently relatively stupid about this (see + :ref:`conflict_resolution`), but in practice, I didn't find its stupidity to + be problematic. + +* **Superior server options:** ``sshd`` is vastly easier to set up and faster + than any DAV-server I've ever seen. Passwordless authentication is also a + huge win, although there are DAV-servers which provide that too. + +* `Something about data integrity + `_. + You'll quickly notice if your hardware is loosing your files, because git + creates checksums of everything. + +Many other CLI programs that need to sync data are based on git, for example +pass_ or ppl_. Those usually hide git behind a convenient CLI interface that at +least autocommits. + +Given that, **the only reason why you should choose vdirsyncer over git is its +compatibility with existing services**: Git can't sync with your :ref:`iCloud +`, :ref:`Exchange server ` or :ref:`ownCloud +`. And not with your smartphone. + +You can also employ a mixture of vdirsyncer and git to enjoy the advantages of +both. This is the approach I am currently using. + +.. _pass: http://passwordstore.org/ +.. _ppl: http://ppladdressbook.org/