PIMSYNC-MIGRATION(7)

📦
version 0.5.10 · 3 versions
, in alpine 3.24, nixos 26.05

okay bestie, buckle up 🫶 this is pimsync-migration(7) — the migration guide from vdirsyncer to pimsync 💅 straight outta the Miscellaneous Information Manual, no cap.

✨ NAME ✨

pimsync-migration — migration guide from vdirsyncer to pimsync. That's the whole name, periodt. If you're moving from vdirsyncer to pimsync, this is your group-chat recap. 💖

💖 DESCRIPTION 💖

This migration guide covers the changes to keep in mind when migrating from vdirsyncer to pimsync. It's geared toward users who already have a working configuration of the previous implementation. So if your vdirsyncer setup is alive and functioning? Perfect, this is literally for you. ✨

🫣 MISSING FEATURES 🫣

vdirsyncer 0.19.3 ships these, but pimsync does not currently have them (the original says “not currently not available” — iconic double-negative chaos, but the meaning is: missing 😭). Here's the list:

  • auth digest — This needs to be implemented as a ‘tower-service’ middleware. Should not be too complicated.
  • partial_sync — This configuration parameter probably won't come back in the same way. A “mirror” is the most likely successor. With this directive set, pimsync(1) would make B a mirror of A. In this mode, exactly one storage MUST be defined a read_only.
  • post_hook — configuration parameter. Future versions might stream events, so external handlers can react to them instead.
  • start_date, end_date, and item_types — configuration parameters for CalDAV storages. These are planned, but no specific time frame.
  • The singlefile storage — which saves all events in a calendar into a single file.
  • Support for Google's flavour of CalDAV and CardDAV — This includes OAuth support.

And these ones are not present and unlikely to be implemented without a compelling use case. Please reach out if you require some of these:

  • Encodings other than UTF-8
  • All metadata is synchronised. Selecting individual fields is not currently possible.
  • The fileignoreext configuration parameter.

🛠️ CONFIGURATION FILE FORMAT 🛠️

The configuration format has changed. The general approach is the same, but the syntax has been greatly simplified for humans to write. Technically, the format is the scfg format. It is documented in detail in pimsync.conf(5).

The following:

[pair.contacts]
a = "contacts_local"
b = "contacts_fastmail"
collections = "all"
conflict_resolution = ["command", "nvim", "-d"]

Becomes:

pair contacts {
        storage_a contacts_local
        storage_b contacts_fastmail
        collections all
        conflict_resolution cmd nvim -d
}

And the following:

[storage.contacts_local]
type = "filesystem"
path = "~/.local/share/contacts/"
fileext = "vcf"

Becomes this:

storage contacts_local {
        type vdir/vcard
        path ~/.local/share/contacts/
        fileext vcf
}

🔐 FETCH MECHANISMS 🔐

The prompt mechanism for fetching passwords has been dropped. Gone. No more prompt. 😭

A fetch definition with a command would previously look like this:

password.fetch = ["command", "hiq", "-dFpassword", "proto=carddavs", "username=…"]

Now a block is provided to password with a single cmd directive specifying the command and its arguments.

password {
        cmd hiq -dFpassword proto=carddavs username=…
}

A fetch definition with a shell now uses a similar syntax:

password {
        shell pass show communication/migadu.com | head -1
}

🔁 MIGRATING FETCH / PROMPT 🔁

Use an external prompter instead. For a GUI prompter, consider using:

password {
        cmd zenity --password
}

pimsync(1) will request passwords in sequence, so no special considerations are required to prevent concurrent prompts. Lowkey convenient. ✨

🧭 MANUAL DISCOVERY IS NO LONGER REQUIRED 🧭

Discovering collections ahead of time is no longer required. Collections are discovered automatically if necessary. The discover command merely prints discovered collections as a convenience for manually configuring collections. It does not affect pimsync's internal state. See pimsync(1) for details.

🪄 AUTOMATIC CREATION OF COLLECTIONS 🪄

If a pair is configured to synchronise all collections from a and a new collection is found on storage A, then the collection will automatically be created on storage B. For scenarios where automatic creation of collections is undesirable, the move is to specify individual collections explicitly instead.

🧪 DRY RUNS ARE NOW POSSIBLE 🧪

It is now possible to execute a dry run, which only prints the tentative plan without executing it. The output is somewhat terse at this stage and not in its final form. This can be used to audit new configurations and ensure that the planned actions make sense. Yes bestie, dry runs are now a thing. 🧚

📁 FILESYSTEM STORAGES HAVE BEEN RENAMED TO VDIR 📁

Filesystem collections have been renamed to vdir. They must now specify what type of items they contain.

A directory with icalendar files should specify:

type = "vdir/icalendar"

A directory with vcard files should specify:

type vdir/vcard

🌈 CUSTOM ENCODINGS FOR VDIR STORAGE 🌈

The vdir storage saves files as UTF-8. If another encoding is required for some scenario, please open an issue at: https://todo.sr.ht/~whynothugo/pimsync

🎀 FILESYSTEM FILEEXT FIELD 🎀

The fileext field for filesystem storages required a leading dot. This is no longer the case; the dot is not considered part of the extensions and should be omitted. Omit the leading dot when porting configurations.

🗂️ COLLECTIONS ARE DECLARED IN A DIFFERENT FORMAT 🗂️

To synchronise all collections from both sides, use:

collections all

To synchronise all collections present on a specific storage, use:

collections from b

🎯 SPECIFYING INDIVIDUAL COLLECTIONS 🎯

Individual collections can be specified by id or by href: file ... id is the name from the discovery process. file ... href is the full path inside the storage.

Generally, using an id is recommended. Using href is intended for situations where discovery is not possible or where multiple collections have the same id. To specify a single collection by id, use:

collection c037725e-e4fd-4b3e-b73d-d5e27d5a90a9

The above will find and synchronise collections with the given id between both storages.

Two different collections can be mapped on each side:

pair my_pair {
        # other fields here

        # first collection
        collection {
                        alias personal
                        href_a /calendars/hugo/c037725e-e4fd-4b3e-b73d-d5e27d5a90a9/
                        href_b /personal/
        }

        # another collection
        collection {
                        alias work
                        id_a work
                        href_b /calendars/work/
        }
}

Specifying collection null is no longer allowed; configuration should point to an explicit collection instead.

🌐 HTTP STORAGE IS NOW CALLED WEBCAL 🌐

The type of the http storage is now webcal, to better reflect its nature; other storages also use HTTP internally.

🆔 WEBCAL COLLECTION ID 🆔

Due to its nature, the WebCal storage has a single collection. However, this collection has no id. A collection id must be provided for it explicitly. This simplifies configurations where it must be synchronised to another calendar with the same collection id.

storage calendars_lessons {
        type http
        collection_id lessons
        url {
                cmd hiq -dFurl proto=webcal alias=lessons
        }
}

🔒 READ ONLY 🔒

The read_only takes no values. Its presence makes a storage read only. To make a storage read-write, remove the directive.

📊 STATUS 📊

Vdirsyncer keeps a status database in order to distinguish whether an item has changed on one side or both. Pimsync does not import this status database in any way. If you are migrating and have existing remote and local storages, make sure that they are in sync before switching over. After the first run, pimsync will build its own status database.

Migrating with out-of-sync storages will result in conflicts during the first run. This is the dramatic part — pls don't skip the sync check. 💀

🔐 TLS CONFIGURATION 🔐

The verify configuration directive is now named tls_root.

The verify_fingerprint configuration directive is now named tls_fingerprint.

🐛 ISSUES 🐛

Please report issues at: https://todo.sr.ht/~whynothugo/vdirsyncer-rs

If you have a working vdirsyncer configuration, and this page is missing details necessary when upgrading, please reach out so this documentation can be improved.

👀 SEE ALSO 👀

k, that's the whole migration guide. Signed with source/version/date energy: PIMSYNC · 2025-04-14 · PIMSYNC-MIGRATION(7) — now go slay those configs, bestie 💅✨💖

📦 where this page comes from