.\" Generated by scdoc 1.11.3 .\" Complete documentation for this program is not available as a GNU info page .ie \n(.g .ds Aq \(aq .el .ds Aq ' .nh .ad l .\" Begin generated content: .TH "pimsync-migration" "7" "2025-03-25" .PP .SH NAME .PP pimsync-migration - migration guide from vdirsyncer to pimsync .PP .SH DESCRIPTION .PP This migration guide covers changes to be kept in mind when migrating from vdirsyncer to pimsync.\& It is geared towards users with a working configuration of the previous implementation.\& .PP .SH MISSING FEATURES .PP The following features are implemented by vdirsyncer 0.\&19.\&3, but are not currently not available in pimsync: .PP .PD 0 .IP \(bu 4 \fBHTTP Digest Auth\fR.\& This needs to be implemented as a \fItower-service\fR middleware.\& Should not be too complicated.\& .IP \(bu 4 \fBpartial_sync\fR configuration parameter.\& This probably won'\&t come back in the same way.\& A \fBmirror\fR 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.\& .IP \(bu 4 Encodings other than UTF-8.\& There are no concrete plans for any specific encoding at this time.\& .IP \(bu 4 \fBpost_hook\fR configuration parameter.\& Future versions might stream events, so external handlers can react to them instead.\& .IP \(bu 4 \fBfileignoreext\fR configuration parameter.\& There are no plans to implement this feature at this time.\& .IP \(bu 4 \fBstart_date\fR, \fBend_date\fR and \fBitem_types\fR configuration parameters for CalDav storages.\& These are planned, but no specific time frame.\& .IP \(bu 4 The \fBsinglefile\fR storage.\& There are no concrete plans at this time.\& The logic for extracting WebCal should make implementing this (in read-only mode) trivial.\& .IP \(bu 4 All metadata is synchronised.\& Selecting individual fields is not currently possible.\& .IP \(bu 4 The \fBreadonly\fR configuration directive is not yet implemented.\& .PD .PP .SH CONFIGURATION FILE FORMAT .PP 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 \fBscfg\fR format.\& It is documented in detail in pimsync.\&conf(5).\& .PP .PP The following: .PP .nf .RS 4 [pair\&.contacts] a = "contacts_local" b = "contacts_fastmail" collections = "all" conflict_resolution = ["nvim", "-d"] .fi .RE .PP Becomes: .PP .nf .RS 4 pair contacts { storage_a contacts_local storage_b contacts_fastmail collections all conflict_resolution nvim -d } .fi .RE .PP And the following: .PP .nf .RS 4 [storage\&.contacts_local] type = "filesystem" path = "~/\&.local/share/contacts/" fileext = "vcf" .fi .RE .PP Becomes this: .PP .nf .RS 4 storage contacts_local { type vdir/vcard path ~/\&.local/share/contacts/ fileext vcf } .fi .RE .PP .SH FETCH MECHANISMS .PP The \fBprompt\fR mechanism for fetching passwords has been dropped.\& .PP A \fBfetch\fR definition with a \fBcommand\fR would previously look like this: .PP .nf .RS 4 password\&.fetch = ["command", "hiq", "-dFpassword", "proto=carddavs", "username=…"] .fi .RE .PP Now a block is provided to \fB\fRpassword\fB\fR with a single \fB\fRcmd\fB\fR directive specifying the command and its arguments.\& .PP .nf .RS 4 password { cmd hiq -dFpassword proto=carddavs username=… } .fi .RE .PP A \fBfetch\fR definition with a \fBshell\fR now uses a similar syntax: .PP .nf .RS 4 password { shell pass show communication/migadu\&.com | head -1 } .fi .RE .PP .SS MIGRATING FETCH / PROMPT .PP Use an external prompter instead.\& For a GUI prompter, consider using: .PP .nf .RS 4 password { cmd zenity --password } .fi .RE .PP pimsync(1) will request passwords in sequence, so no special considerations are required to prevent concurrent prompts.\& .PP .SH MANUAL DISCOVERY IS NO LONGER REQUIRED .PP Discovering collections ahead of time is no longer required.\& Collections are discovered automatically if necessary.\& .PP The \fBdiscover\fR 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.\& .PP .SH AUTOMATIC CREATION OF COLLECTIONS .PP If a pair is configured to synchronise all collections \fBfrom a\fR and a new collection is found on storage A, then the collection will automatically be created on storage B.\& .PP For scenarios where automatic creation of collections is undesirable, individual collection should be explicitly specified instead.\& .PP .SH DRY RUNS ARE NOW POSSIBLE .PP 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.\& .PP This can be used to audit new configurations and ensure that the planned actions make sense.\& .PP .SH FILESYSTEM STORAGES HAVE BEEN RENAMED TO VDIR .PP Filesystem collections have been renamed to \fBvdir\fR.\& They must now specify what type of items they contains.\& .PP A directory with icalendar files should specify: .PP .nf .RS 4 type = "vdir/icalendar" .fi .RE .PP A directory with vcard files should specify: .PP .nf .RS 4 type vdir/vcard .fi .RE .PP .SH CUSTOM ENCODINGS FOR VDIR STORAGE .PP The vdir storage saves files as UTF-8.\& If another encoding is required for some scenario, please open an issue at: .PP .RS 4 https://todo.\&sr.\&ht/~whynothugo/pimsync .PP .RE .SH FILESYSTEM FILEEXT FIELD .PP The \fBfileext\fR 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.\& .PP .SH COLLECTIONS ARE DECLARED IN A DIFFERENT FORMAT .PP To synchronise all collections from both sides, use: .PP .nf .RS 4 collections all .fi .RE .PP To synchronise all collections present on a specific storage, use: .PP .nf .RS 4 collections from b .fi .RE .PP .SS SPECIFYING INDIVIDUAL COLLECTIONS .PP Individual collections can be specified by \fBid\fR or by \fBhref\fR: .PP .PD 0 .IP \(bu 4 The \fBid\fR is the name from the discovery process.\& .IP \(bu 4 The \fBhref\fR is the full path inside the storage.\& .PD .PP Generally, using an \fBid\fR is recommended.\& Using \fBhref\fR is intended for situations where discovery is not possible or where multiple collections have the same \fBid\fR.\& .PP To specify a single collection by id, use: .PP .nf .RS 4 collection c037725e-e4fd-4b3e-b73d-d5e27d5a90a9 .fi .RE .PP The above will find synchronise collections with the given id between both storages.\& .PP Two different collections can mapped on each side: .PP .nf .RS 4 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/ } } .fi .RE .PP Specifying collection \fBnull\fR is no longer allowed; configuration should point to an explicitly collection instead.\& .PP .SH HTTP STORAGE IS NOW CALLED WEBCAL .PP The type of the \fBhttp\fR storage is now \fBwebcal\fR, to better reflect its nature; other storages also use HTTP internally.\& .PP .SH WEBCAL COLLECTION ID .PP 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.\& .PP .nf .RS 4 storage calendars_lessons { type http collection_id lessons url { cmd hiq -dFurl proto=webcal alias=lessons } } .fi .RE .PP .SH STATUS .PP 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, makes sure that they are in sync before switching over.\& After the first run, pimsync will build its own status database.\& .PP Migrating with out-of-sync storages will result in conflicts during the first run.\& .PP .SH ISSUES .PP Please report issues at: .PP .RS 4 https://todo.\&sr.\&ht/~whynothugo/vdirsyncer-rs .PP .RE 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.\& .PP .SH SEE ALSO .PP .PD 0 .IP \(bu 4 pimsync(1) .IP \(bu 4 pimsync.\&conf(5) .IP \(bu 4 \fBscfg\fR, simple configuration format, https://git.\&sr.\&ht/~emersion/scfg .IP \(bu 4 hiq(1), query a himitsu(7) key store