========================= Full configuration manual ========================= Vdirsyncer uses an ini-like format for storing its configuration. All values are JSON, invalid JSON will get interpreted as string:: x = "foo" # String x = foo # Shorthand for same string x = 42 # Integer x = ["a", "b", "c"] # List of strings x = true # Boolean x = false x = null # Also known as None .. _general_config: General Section =============== :: [general] status_path = ... - ``status_path``: A directory where vdirsyncer will store some additional data for the next sync. The data is needed to determine whether a new item means it has been added on one side or deleted on the other. Relative paths will be interpreted as relative to the configuration file's directory. See `A simple synchronization algorithm `_ for what exactly is in there. .. _pair_config: Pair Section ============ :: [pair pair_name] a = ... b = ... #collections = null #conflict_resolution = null - Pair names can consist of any alphanumeric characters and the underscore. - ``a`` and ``b`` reference the storages to sync by their names. - ``collections``: A list of collections to synchronize when ``vdirsyncer sync`` is executed. See also :ref:`collections_tutorial`. The special values ``"from a"`` and ``"from b"``, tell vdirsyncer to try autodiscovery on a specific storage. If the collection you want to sync doesn't have the same name on each side, you may also use a value of the form ``["config_name", "name_a", "name_b"]``. This will synchronize the collection ``name_a`` on side A with the collection ``name_b`` on side B. The ``config_name`` will be used for representation in CLI arguments and logging. Examples: - ``collections = ["from b", "foo", "bar"]`` makes vdirsyncer synchronize the collections from side B, and also the collections named "foo" and "bar". - ``collections = ["from b", "from a"]`` makes vdirsyncer synchronize all existing collections on either side. - ``collections = [["bar", "bar_a", "bar_b"], "foo"]`` makes vdirsyncer synchronize ``bar_a`` from side A with ``bar_b`` from side B, and also synchronize ``foo`` on both sides with each other. - ``conflict_resolution``: Optional, define how conflicts should be handled. A conflict occurs when one item (event, task) changed on both sides since the last sync. See also :ref:`conflict_resolution_tutorial`. Valid values are: - ``null``, where an error is shown and no changes are done. - ``"a wins"`` and ``"b wins"``, where the whole item is taken from one side. - ``["command", "vimdiff"]``: ``vimdiff `` will be called where ```` and ```` are temporary files that contain the item of each side respectively. The files need to be exactly the same when the command returns. - ``vimdiff`` can be replaced with any other command. For example, in POSIX ``["command", "cp"]`` is equivalent to ``"a wins"``. - Additional list items will be forwarded as arguments. For example, ``["command", "vimdiff", "--noplugin"]`` runs ``vimdiff --noplugin``. Vdirsyncer never attempts to "automatically merge" the two items. .. _partial_sync_def: - ``partial_sync``: Assume A is read-only, B not. If you change items on B, vdirsyncer can't sync the changes to A. What should happen instead? - ``error``: An error is shown. - ``ignore``: The change is ignored. However: Events deleted in B still reappear if they're updated in A. - ``revert`` (default): The change is reverted on next sync. See also :ref:`partial_sync_tutorial`. - ``metadata``: Metadata keys that should be synchronized when ``vdirsyncer metasync`` is executed. Example:: metadata = ["color", "displayname"] This synchronizes the ``color`` and the ``displayname`` properties. The ``conflict_resolution`` parameter applies here as well. .. _storage_config: Storage Section =============== :: [storage storage_name] type = ... - Storage names can consist of any alphanumeric characters and the underscore. - ``type`` defines which kind of storage is defined. See :ref:`storages`. - ``read_only`` defines whether the storage should be regarded as a read-only storage. The value ``true`` means synchronization will discard any changes made to the other side. The value ``false`` implies normal 2-way synchronization. - Any further parameters are passed on to the storage class. .. _storages: Supported Storages ------------------ CalDAV and CardDAV ++++++++++++++++++ .. autostorage:: vdirsyncer.storage.dav.CalDAVStorage .. autostorage:: vdirsyncer.storage.dav.CardDAVStorage Google ++++++ At first run you will be asked to authorize application for google account access. To use this storage type, you need to install some additional dependencies:: pip install vdirsyncer[google] Furthermore you need to register vdirsyncer as an application yourself to obtain ``client_id`` and ``client_secret``, as `it is against Google's Terms of Service to hardcode those into opensource software `_: 1. Go to the `Google API Manager `_ and create a new project under any name. 2. Within that project, enable the "CalDAV" and "CardDAV" APIs (**not** the Calendar and Contacts APIs, those are different and won't work). There should be a searchbox where you can just enter those terms. 3. In the sidebar, select "Credentials" and create a new "OAuth Client ID". The application type is "Other". You'll be prompted to create a OAuth consent screen first. Fill out that form however you like. 4. Finally you should have a Client ID and a Client secret. Provide these in your storage config. You can select which calendars to sync on `CalDav settings page `_. .. autostorage:: vdirsyncer.storage.google.GoogleCalendarStorage .. autostorage:: vdirsyncer.storage.google.GoogleContactsStorage remoteStorage +++++++++++++ `remoteStorage `_ is an open per-user data storage protocol. Vdirsyncer contains **highly experimental support** for it. .. note:: Do not use this storage if you're not prepared for data-loss and breakage. To use them, you need to install some optional dependencies with:: pip install vdirsyncer[remotestorage] .. autostorage:: vdirsyncer.storage.remotestorage.RemoteStorageContacts .. autostorage:: vdirsyncer.storage.remotestorage.RemoteStorageCalendars Local +++++ .. autostorage:: vdirsyncer.storage.filesystem.FilesystemStorage .. autostorage:: vdirsyncer.storage.singlefile.SingleFileStorage Read-only storages ++++++++++++++++++ These storages don't support writing of their items, consequently ``read_only`` is set to ``true`` by default. Changing ``read_only`` to ``false`` on them leads to an error. .. autostorage:: vdirsyncer.storage.http.HttpStorage