Sync

Keep your library and workspaces in step across several devices. Data is encrypted on this device before it is uploaded, by default, and comes with a recovery code. You choose where it goes: the CiteDesk sync service, or your own S3-compatible storage or WebDAV server. The sync settings are on the Settings > Sync page. The last line of the Account page shows the current sync status, and Sync Settings… there takes you to the same page.

The top of the page is the status card: the space name, where it is stored, the encryption mode, the current status, and Sync Now, Pause, and Resolve Conflicts… when there are conflicts. Things that need your attention, such as a recovery code that has not been confirmed as saved, a file problem, or a transfer that has not finished, appear as banners under the status card. Below it are three groups: This Device (workspaces, file syncing, automatic sync, sync scopes), Security (recovery code and devices; only for end-to-end encrypted spaces) and Storage and History (usage and diagnostics, version history and cleanup). Advanced at the bottom (transfer, disconnect, reset local sync credentials) can be collapsed and starts collapsed; it opens by itself while a transfer is unfinished or the keys on this device cannot be read. The buttons described below are in these groups.

What is synced#

Synced:

• The library: references, notes, attachments (including attachment files stored in the library), annotations, collections, saved searches, tag colors, and the last-read time of attachments.
• Workspaces: the Markdown files and resource files of the workspaces you have added to sync. On this device they remain ordinary Markdown files that any other program can open.

Not synced: application settings, window layout, local paths, sign-in and storage credentials, cookies, proxy settings, the retraction list, the full-text index, reading positions, and the CSL styles you imported. Attachment files that are linked to other places on this computer are not uploaded either; other devices see only the link information.

Things to know first:

• A sync space is one library plus any number of workspaces. Workspaces are added one at a time; see Workspaces.
• When both sides changed the same thing and the changes cannot be merged automatically, the time of the edits never decides which one wins. Both versions are kept until you choose; see Conflicts.
• This sync is CiteDesk's own and does not interoperate with the Zotero sync service. To exchange data with Zotero, use import and export; see Importing and Exporting References.
• Without a network connection everything works as usual. Changes are kept on this device and sync automatically once you are back online.

Choosing a storage location#

Under Sync Space, choose the sync method first, then click Connect and Check (Verify Server for your own storage).

• CiteDesk Sync Service: uses the account you are signed in to on the Settings > Account page; you do not enter storage details. You cannot connect while signed out.
• S3-Compatible Storage: enter the endpoint, region, bucket, access key ID and secret access key. A session token is needed only for temporary credentials. The prefix is optional; if you fill it in, it must be a dedicated, empty location. Some self-hosted services (MinIO, for example) need Path-style access turned on.
• WebDAV: enter the URL, user name and password.

What your own storage must satisfy:

• Only https URLs are supported, and the URL cannot contain a user name, password, query string or fragment.
• The location must be dedicated and empty. The sync space stores data in its own format there; it is not an ordinary folder that other programs can edit.
• The storage must support conditional writes (create only if absent, replace only if unchanged), strong version identifiers (ETag) and read-after-write. The check lists whether each is supported and writes a few temporary test objects, which it then removes; if it cannot remove them, it asks you to delete the directories whose names begin with .probe- by hand. Storage that fails the check cannot be used. CiteDesk will not fall back to plain overwriting, because then two devices would overwrite each other's changes.

Credentials are kept only on this device, in a file in the app's profile folder that only you can read and write, stored as plain text or encrypted with the system keychain according to Credential Storage on This Computer on the Account page. If they cannot be written to that file, you will have to enter them again after quitting the application. When the storage rejects the saved credentials or this device has none, sync stops and shows Enter Credentials…. The location must be the same one the space is bound to, and to change location you use Transfer. The fields in the window that are not secret (endpoint, region, bucket, prefix, URL and so on) are already filled in with the values the space is bound to; you only enter the secret part again. If the saved credentials or key cannot be read (for example because that file is damaged, or the system keychain has no matching key), you can Reset Local Sync Credentials… and then enter the credentials again or fetch the key back with the recovery code. This affects neither the remote data nor the library on this device.

Creating and joining a space#

Once the check passes, either create a new space or join an existing one.

Creating a space. Give it a name to recognize it on your devices. There are three kinds of protection:

• End-to-end encryption (default): content is encrypted on this device before it is uploaded, so the storage provider and anyone else who can reach that location cannot read it. A recovery code is shown after creation; see Recovery code. On the CiteDesk sync service, the server can see how many versions there are, when they were written and how large the objects are, because it enforces the retention period itself, but not the content; see Keeping history.
• CiteDesk keeps the key (only on the CiteDesk sync service): content is still encrypted on this device, but the sync server keeps a copy of the key, so the operator of the server can technically decrypt everything in the space. In return the data can be recovered even if you lose the recovery code; see CiteDesk keeps the key.
• No encryption: references, notes, annotations, collections, tags and attachments stored in the library are kept as plain text in the chosen location.

The protection is fixed when the space is created and cannot be changed in place; to change it you transfer to a new space.

Joining a space. On the new device, choose the same storage location, select the existing space, and get the key in any one of these ways (a space without encryption needs none, but after joining, changes from this device are uploaded as plain text):

• enter the recovery code; see Recovery code;
• have another device that has already joined the space approve it; see Approving a new device;
• for a space where CiteDesk keeps the key, approve in the browser and retrieve the key from the server; see CiteDesk keeps the key.

Joining an existing space requires the library on this device to be empty: no references, notes, attachments, annotations, collections, searches or colored tags. Two libraries that both have content are not merged automatically and do not overwrite each other; joining is simply refused. If this device already holds your data, export it first and then join with a fresh data directory; see Data Directory and Backups.

Recovery code#

The recovery code lets you join an encrypted space from a new device, and recover your data when the key on this device is lost.

• After a space is created, the recovery code is shown in a window, once only. Write it on paper or keep it in a password manager, and do not store it inside the sync space. Copy the Recovery Code puts it on the clipboard.
• Check I have saved the recovery code in a safe place and click Confirm Saved; creation is complete only then. Clicking outside the window or pressing Esc does not close it, because closing it means you can never see this code again. If you leave with the close button without confirming, the settings page warns that the recovery code has not been confirmed as saved, and you can regenerate one or cancel the creation.
• Neither CiteDesk nor the sync server keeps the recovery code. If you lose the recovery code and no authorized device remains, the remote data cannot be recovered, and the consequences are yours.
• When you enter a recovery code, spaces and hyphens are ignored. Repeated wrong entries are limited for a while.
• When the key on this device cannot be read (a new device, or the key saved on this device is damaged or was reset), sync shows Recovery code needed. Enter the recovery code in the sync settings and click Unlock; sync continues and no data on this device is lost. You can also have another device approve this one; see Approving a new device.
• Export Recovery Material…: in the recovery code window, and after a successful check, you can save the space name, the recovery code and short instructions to a text file. The file is plain text. Together with access to the storage location it can read all synced content, so keep it as carefully as the recovery code itself and do not put it in the sync space or a cloud drive.

If you lose the recovery code but still have an authorized device, use Regenerate the Recovery Code… on that device to get a new one. Regenerating changes only the code used from now on: new devices must join with the new code, and the old code can no longer be used to join; but this is not a revocation, because anyone holding the old code and an old copy of the data may still unlock the same key. The only way to make a leaked old code useless is to choose Replace the master key when you transfer; see Transfer.

Verifying the recovery code#

After a while you may not be sure the recovery code you hold is still right. On the Sync page in Settings, in the Security group, choose Verify Recovery Code… and enter it: if it matches, the time of the check is recorded; if not, it is not the currently valid recovery code, so find the correct one or, while an authorized device remains, Regenerate the Recovery Code…. Verifying does not unlock anything and does not change the state of sync. The same group always shows a line, Last recovery code check, saying how many days ago it was.

A reminder appears at the top of the library page on this schedule: on day 14 and day 90 after you confirmed saving the code, then every 180 days; each successful check restarts the timer from that moment. Remind me later or the close button on the reminder brings it back after 7 days. Reminders are kept on this device only, each device reminds on its own, and the writing window is never interrupted. Spaces where CiteDesk keeps the key, and spaces without encryption, show no reminder.

Approving a new device#

A new device does not need the recovery code if a device that has already joined the space, and has unlocked its key, approves it.

1. On the new device select the space and click Approve via Another Device…. The window shows a pairing code (like XXXX-XXXX-XXXXX) and a countdown.
2. On the old device open the Sync page in Settings, click Approve a New Device… and enter the pairing code shown on the new device.
3. The app shows a confirmation window with the new device's name, system, CiteDesk version and request time. That information is reported by the device itself and only helps you recognise it; what actually ties the two devices together is the pairing code you copied across by hand. Click Approve only if it is the device you are using.

Notes:

• The pairing code is valid for 10 minutes and works once. If it expires, or you want another, start again on the new device. The pairing code exists only on the new device's screen and never travels over the network.
• Entering the wrong code repeatedly on the old device pauses further attempts (5 wrong entries within 10 minutes pause it for 10 minutes).
• Once approved, that device holds the key of the space and can read and change everything in it. An approved key cannot be taken back, and content already downloaded to that device cannot be taken back either. To keep it from reading or writing later, revoke its access at the storage provider or in User Center (this takes a while to take effect) and replace the key by transferring with a new master key.
• The devices this device has approved are listed in the sync settings (name and time as reported by the device). CiteDesk keeps no device list on the remote and has no remote Revoke button: such a list could only hold what devices report about themselves, and deleting a row would not take back the key in their hands.
• A device that is already bound but has lost its key can unlock the same way.

CiteDesk keeps the key#

This is one of the protections you can choose when creating a space, and only the CiteDesk sync service offers it.

• Content is still encrypted on this device before upload, but the sync server also keeps a copy of the key. So the operator of the server can technically decrypt everything in this space, and you should know that; the server hands the key out only when you approve a retrieval, and never uses it itself to decrypt content.
• Benefit: if you lose the recovery code and no other authorized device remains, the data can still be recovered. A space with end-to-end encryption cannot be recovered in that situation.
• Before you create one, your account must already have an authenticator set up in User Center. A recovery code is still generated and you may finish without ticking “saved”; it is a fallback for when the service is unavailable.
• Retrieving the key: on a new device (or a device whose key is unavailable) choose Retrieve Key from CiteDesk…. The app opens the approval page of User Center in your system browser and shows a verification code (like XXXX-XXXX) in its window. Sign in in the browser, verify with your password and authenticator, enter the verification code shown in the app window, and approve; the key then arrives in the app by itself. The verification at approval time is valid for 15 minutes only, and each account can retrieve at most 10 times a day.
• The sync spaces page of User Center lists each space's protection and its key retrieval record (time, device name, result).
• The protection is fixed when the space is created. A space with end-to-end encryption can be transferred into custody; changing custody back to end-to-end encryption must also replace the master key, because the server already knows the old one.

Workspaces#

Sync the Markdown files and resource files in a workspace.

• Sync the Current Workspace…: give the workspace a name to recognize it on other devices, and add it to sync.
• Pull…: on another device, pick one of the workspaces that already exist remotely and download it into a folder on this device.
• Stop Syncing: take the workspace out of sync. The files on this device are not touched.

Only the workspace that is currently open is synced. For workspaces that are added to sync but not open, remote changes wait and are applied when you open them. The library is always synced. The binding of a workspace is recorded on this device: if its folder was renamed, moved, or is not the original one, sync stops, and you must select the folder again and confirm it is this workspace.

The Sync Scope table on the settings page lists each scope (the library and every workspace) with the number of items to upload, to apply, files and conflicts, and the time of the last sync. Files skipped during sync, for example because their paths are not valid, are listed below the table.

When a reference ID is renamed#

Citation markers in Markdown contain the reference ID. If another device changed a reference's ID, documents in the current workspace on this device may still contain markers with the old ID after sync. Sync never rewrites your documents on its own; it offers suggestions and you confirm.

• A notice appears at the top of the Citations page of the writing sidebar: Sync found references whose IDs changed: N citation marks in the current workspace (in M files) still use the old IDs and can be rewritten. Click Review… to open the Reference ID Rewrite Suggestions window. The section of the same name in the sync settings lists the same suggestions.
• The window lists each file with the old and the new ID. Tick the ones to rewrite (Select All, Select None) and click Apply Selected. The system asks you to confirm once more before applying, and only the listed places are rewritten.
• Where the reference cannot be found, the old ID is now used by another reference, or the history is ambiguous, the reason is shown and that suggestion cannot be applied.

Attachment files#

Download files under File Syncing decides when attachment files are downloaded to this device:

• at sync time: attachment files are downloaded along with sync.
• as needed: sync brings only the metadata, and a file is downloaded when you open the attachment.

If a file transfer runs into trouble it is retried automatically; you need not do anything. Files larger than sync allows are skipped and everything else syncs as usual; when the storage is full, files cannot be uploaded for now and the rest still syncs. Under Usage and Diagnostics, Check Usage shows how much space the remote uses, and Export Diagnostics… writes a diagnostic file you can hand to whoever is helping you.

Sync markers on objects#

Once a sync space is bound, a small icon appears at the end of the Title cell in the reference list and says why a row is not yet in step with the remote. Rows that are in step show nothing. Rest the pointer on the icon to read the explanation.

When an attachment is selected, the attachment information in the right pane has a Sync row with the same explanation. While the file is on the remote and not downloaded, the row has a Download File button; while it downloads, the row shows progress and a Cancel Download button. For an attachment linked to another place on this computer, the row says that sync carries only the link, not the content of the file.

During file transfers, the sync status panel and the tooltip of the sync button show Syncing files, with how many files are being uploaded and downloaded and how much has been transferred.

Version history#

Every change is kept on the remote, so you can go back to an older version. Version history reads the remote, so it needs a connection; for an end-to-end encrypted space this device must also have the key.

• History of a single item: select a reference, note or attachment in the items list and choose Version History… from the context menu; for a file, right-click it in the file list on the left and choose Version History…. The left side lists every version of the item by time, saying whether it was made on this device or another device and whether it was a creation, an edit, a move to the Trash, a restore or a permanent deletion. The right side previews the selected version next to the current one. With Show only differences from the current version checked, only the fields that differ (references, notes, attachments) or the lines that differ (text files) are listed. Copy puts the previewed content on the clipboard.
• Restore This Version writes the selected version as the item's current content. The restored content syncs to your other devices, and the existing history is never rewritten or deleted, so you can restore back again afterwards; if another device changed the same place meanwhile, it is handled as a conflict. When the selected version is the latest, the window says so.
• Permanently deleted items also appear in the version list, with Permanently deleted as the last version. Select an earlier version and choose Restore This Version: the item comes back with its original identity, its relations and attachment files reconnect, and it is added back to the collections it was in.
• Versions whose content cannot be read: when a version is past the retention period and was cleaned up, or was cleared, it still appears in the list but reads Content unavailable; select it and the right side explains which case it is. It cannot be previewed or restored. There are four wordings: Earlier history has been cleaned up (it is past the retention period); cleared by a clear request (the server records that Clear old content of deleted items removed this version, which is the server's own statement); History unavailable, with how many days ago this device still saw the version as current (it can no longer be read; the application does not claim to know who removed it; you can export diagnostics); and History is unavailable, and the cause and time cannot be confirmed (this device does not have enough records to tell why the content is unavailable or since when, for example on a new device).
• Deleted Items: View Deleted Items… in the Storage and History group of the Sync page lists permanently deleted items; select several and choose Restore Selected. Items in the Trash are not listed there; restore them from the library Trash. When the content from before the deletion cannot be read, the row says why (the same four wordings as above) and cannot be ticked.
• Attachment files: when the restored version has different file content, that content is fetched completely from the remote and verified before anything is written. If any part is missing on the remote, nothing is restored and the window says what is missing. The file that is replaced is kept in the sync-recovery folder in the data directory.
• Reference IDs: restoring a reference can bring back its older reference ID, or give it another one when the older ID is now used by a different reference. The changes are listed when it finishes; citations in the text that use the previous ID show as missing and can be handled as described in When a reference ID is renamed.
• Restoring is not possible while this item has changes that have not been sent, while a conflict involving it is unresolved, or when the remote cannot be read. Sync once and try again; the window says why.
• The version list shows whether each version came from This device or Another device. For a space that was transferred to another backend, the history carried over by the transfer is listed as usual; history that was older, or could not be read at the time of the transfer, stays in the old location and cannot be read here; the version list says so.

Going back to a previous state#

Return a whole library or a whole workspace to how it was at an earlier moment. In the Storage and History group of the Sync page choose Go Back to a Previous State…, pick the scope (if there is more than one) and the moment, then choose how to restore:

• Recover and overwrite (default): content that existed then is brought back, and edited content returns to how it was. Anything created after that moment is left alone.
• Exactly as it was: on top of that, content created after the moment is dealt with too. In the library it is moved to the Trash, where it can be restored again; in a workspace the files are moved to the system Trash. Nothing is deleted outright.

The window lists how many items will be overwritten, recovered and moved to the Trash. After Restore the application asks once more. Once you confirm, the files that are needed are fetched first, then everything is written and published in one step. The result syncs to your other devices, and the existing history is not rewritten. To undo it, open this window again and choose the moment just before the restore.

Some moments in the timeline are marked Cannot restore, and the right side says why when you select one: it includes old content of deleted items that was cleared, or content it depends on was cleaned up after the retention period. Such a moment is never skipped silently; choose a later one.

These cases are reported or skipped and never handled on their own: when a file's path in a workspace is now used by another file, that file is skipped and not renamed; collection members whose items no longer exist are not added back; on an attachment that gets an older file back, annotations created after that version stay as they are and their positions may not match. Last-read times are not restored. The application backs up the library before it starts.

Cleaning up unused remote data#

A space on the CiteDesk sync service has no Clean Up Unused Remote Data item: data that no version uses and history that has expired are cleaned up by the server from its own records and clock, with no device needed online; see Keeping history. In its place the Clear old content of deleted items row has a Clear… button, so you can free space yourself:

• It clears the old versions' content of objects that were permanently deleted. The application asks once first and says three things: this old content can no longer be restored from within CiteDesk; the server deletes it for good only after 14 days, and until then only the operator can put it back; and content packaged or shared with other content may free its space later.
• This is you shortening your own history, and cleared content is no longer covered by the retention period. Current data and the records of deleted objects are not affected: a cleared object stays listed under Deleted Items, marked as cleared and not restorable.
• A space can be cleared once an hour.

What follows is Clean Up Unused Remote Data… on your own storage (S3-compatible storage, WebDAV).

Interrupted syncs and publications superseded by another device leave data on the remote that no version uses. In the Storage and History group of the Sync page choose Clean Up Unused Remote Data…; the application works out how much can be cleaned up and deletes it after you confirm.

• When you clean up orphaned data by hand, all version history and the records of deleted items are kept (this is a different cleanup from the one under Keeping history below, which follows the retention period). Cleanup only deletes data that no version uses, so version history and restoring are not affected.
• Data created in the last 7 days is not deleted, and neither is data for which the storage did not report a time.
• Cleanup is never automatic; it runs only when you choose it. Check Usage under Usage and Diagnostics lists the space used by current versions, used only by history, that can be cleaned up, and that is still in the grace period.
• Deleting needs storage credentials that have delete permission. Data deleted from your own S3-compatible storage or WebDAV cannot be recovered except through the storage provider's own versioning, which is worth turning on first.
• If another device is cleaning up, or this device has an unfinished publication or transfer, cleanup is postponed; try again later.

Keeping history#

By default every change stays on the remote for good. With a retention period, only the versions from the last stretch of time are kept, and older ones are deleted, so the space stops growing without limit.

• Sync service: the service decides how long history is kept for your account tier. Settings shows the number of days and cannot change it.
• The server does this itself, with no device online: expiry and deletion are done entirely by the server from its own records and clock, the same for the desktop app and the web; your devices cannot change it and have nothing to do for it. A version that a newer one replaced expires once it has been replaced for the whole retention period, and the old content of a permanently deleted object expires once it has been deleted for that long. Expired content is not deleted right away: it first enters a 14-day grace period in which only the operator can put it back, and it is deleted for good when that ends. Current versions, deletion records and the archives left by a transfer are never deleted automatically.
• Your own storage (S3-compatible storage, WebDAV): in the Storage and History group of the Sync page, Keep history can be Keep all (the default) or Custom… with a number of days, at least 30. The whole space shares this setting, and every device follows it.
• Shortening it asks first, because deleted old versions cannot be restored. Lengthening it, or going back to Keep all, does not ask.
• After old history is cleaned up, the earliest version in the version history reads Earlier history cleaned up, and nothing before it can be restored. Items permanently deleted even earlier stay listed under Deleted Items, marked as cleaned up and not restorable. Current data is not affected.
• The trash and the retention period: items in the trash are permanently deleted automatically after 30 days by default (the trash auto-empty days setting, as in Zotero). Only after an item has been permanently deleted for the whole retention period is its content trimmed from history. Moving an item to the trash counts as one ordinary change and is never deleted because of the retention period. The retention period only deletes old versions that newer versions have replaced; data that exists now is never deleted.
• Check Usage under Usage and Diagnostics shows the number of days kept and the date you can Restore back to.
• Usage on the official space is all your sync data in the official storage plus what has not been freed yet: current data, history within the retention period, archives, content still in its grace period, and reserved uploads all count. Check Usage shows used / limit, with a small part kept for delete operations that ordinary uploads cannot use, then splits the usage into seven separate kinds: uploads in progress, waiting to be freed, archives, current data, sync records, history versions and awaiting cleanup. The server calculates the breakdown from time to time, so it may differ slightly from the total, and the calculation time is shown. Old content packaged together with content still in use cannot be freed on its own; it is counted once and explained in a separate line. For the waiting-to-be-freed part, the dates the server plans to clean it up are shown too (your local time zone; only a plan, which slips if the server pauses cleanup or cleanup is blocked).
• When the space is full: over the limit, only new uploads are blocked. Changes are still saved on this device and queued, and nothing already stored is deleted. Storage and History lists, in order, what can free space and what each one waits for: history past the retention period being cleaned up by the server; clearing the old content of deleted items (freed after the 14-day grace period); deleting an archive in the User Center (freed 14 days after you start); asking the operator to raise the limit; moving the space to your own storage and then deleting the sealed old copy on the official service (freed after 14 days); and closing the account (which deletes all sync data on the official service).
• What the server therefore knows: to enforce the retention period itself, the CiteDesk sync service can see how many versions each item has, which version replaced which, whether an item has been deleted, which items changed in the same write, and the sizes and write and access times of objects. It cannot tell whether an item is a reference, a note or an attachment, nor how they are attached to each other. In an end-to-end encrypted space it cannot see the text of references, notes and annotations, the content and names of attachment files, the text and paths of workspace files, or collection and space names; in a plain-text space and in a space where CiteDesk keeps the key, the operator can read the content.
• Cleanup on your own storage is checked when sync is idle, at most once a day, so shortening the period does not delete anything right away.
• Your own storage needs credentials that can delete files. Without that permission old history is not cleaned up, and Usage and Diagnostics says so.

Sync status#

The library view header has a sync button (an icon with two arrows), and the status bar at the bottom of the application has a "Sync: …" item.

• Clicking the sync button syncs right away when all is well; when there is a problem, you are offline or sync is paused it opens the Sync status panel; if sync is not set up yet it opens the sync settings. Clicking the status bar item also opens the panel.
• The panel shows the time of the last sync, how many items each scope has waiting, an explanation of any problem, and the buttons Resolve Conflicts…, Sync Now, Pause Sync or Resume Sync, and Open Sync Preferences. Changes made while paused are kept on this device and uploaded after you resume.

The sync settings have a Sync automatically checkbox, on by default. When it is off, local changes, periodic checks, application startup and network recovery no longer trigger a sync; sync runs only when you choose Sync Now, and your changes are still saved on this device. This differs from Pause Sync: while paused, even Sync Now does not run, and automatic downloads in progress are cancelled.

Common states:

Common reasons for Sync stopped: the remote version is older than the one this device has seen (it may have been rolled back or restored from a backup); the remote shows two histories that cannot be reconciled; the remote data format does not match this application; the entry point of the sync space cannot be found; the space was transferred elsewhere; or the account you are signed in with differs from the account the space is bound to. When this happens, do not keep writing; follow the message, and export diagnostics if needed. A system clock that differs too much from the server's can also make the secure connection fail; set your system time correctly.

Conflicts#

When this device and the remote made changes to the same object that cannot be merged automatically, sync pauses that item and waits for your choice. Until you choose, both versions are kept and nothing is lost. Click Resolve Conflicts… in the sync status panel or the sync settings to open the conflict window.

On the left is the list of conflicts; on the right is the current one. It first says what kind of conflict it is, then shows the Local version, the Remote version and the Common base (the version both sides had before each changed it) side by side. Objects in the library are compared field by field. For a field conflict you can choose which side to keep for each field (see Merging field by field below); other conflicts, such as deletions, use the options listed below.

The available ways to resolve depend on the kind of conflict: Keep the local version, Keep the remote version, Merge field by field (see below), Keep both (one of them is stored under a new name), Use the merged text (merge by hand in the box below, starting from the local or the remote version), Restore the object (undo the deletion), Delete the object (accept the deletion), and Rename the local object (give the local object a new name so both versions exist). After choosing, click Apply This Choice; move between items with Previous and Next.

• A choice that deletes objects lists the objects affected; you must tick the confirmation before applying, and the system asks once more afterwards.
• Use the local version for all remaining conflicts (or the remote version), below the list, handles the current item and every item after it with the side you picked, with a single confirmation (with a very large number it works in batches and asks once per batch). Bulk deletions and invalid remote objects are not included. Afterwards the window says how many were resolved; items that changed after you confirmed were left alone and are marked changed, left alone, so review them again; items that could not be resolved are marked not resolved, with the reason.
• Some conflicts involve several records and are applied together only after all of them have a choice; the window tells you how many are still missing.
• Before the remote version of an attachment is adopted, the complete directory of the local attachment is kept as it was in the recovery folder inside the local data directory, and is not simply removed. The notice for this item has a Show File button that opens that folder.

Merging field by field. When the two sides changed different fields of the same object and only some of the fields conflict, you can merge instead of taking a whole side. A table appears below with the conflicting fields and, for each, the base, local and remote values and the result. For each field choose Local or Remote. Local is preselected. The top-level fields of a reference (title, date and so on) can also be set to Edit, where you write a new value. Fields whose values are not text (numbers, lists and so on) are written as JSON, for example 3 or [1,2]; if what you wrote is not valid, you cannot apply it. Changes that do not conflict are applied automatically. If the result does not meet the library's requirements (for example a date or number written the wrong way), it is not saved, the window says why, and what you typed stays; correct the field or choose one side.

Unfinished attachment file operations#

Renaming, relinking or converting attachment files, attaching a file to an attachment, and sync writing files into a workspace all change files and the library together. If one of these operations is interrupted (for example the application crashed, or another program held the files) and cannot finish by itself, a banner appears at the top of the library page: N attachment file operations did not finish. Click Review….

No file has been deleted. Whatever was moved aside from its original place is in the recovery folder shown for each entry. Until it is dealt with, the attachments and paths concerned cannot be renamed, relinked or converted; other attachments are not affected.

Each entry tells you whether the record in the library has already been changed, and lists the paths involved and the recovery folder. Each attachment has a Show File button that shows its file in Finder or your system's file manager; the recovery folder has Show File, which opens that folder, and Copy Path. The ways to resolve it:

• Retry: try the operation again. If another program is holding the files, close it first.
• Keep the Current Files: treat the files on disk as they are now and make the library record agree with them. The old content that does not match is not deleted; it is moved into the recovery folder.
• Restore to Before the Operation: put both the files and the library record back as they were before the operation began. Half-finished new content is not deleted; it is moved into the recovery folder.

The last two ask you to confirm first. The window may also contain a part titled "Attachment content that sync could not finish installing": while installing attachment files, sync found that material on this device did not match the record (for example an outside program rewrote an old directory that had been moved aside), and moved it as it was into the given folder without deleting anything. The library works as usual; use Show File to open that folder and find the files if you need them.

Transferring to another storage location#

Transfer to Another Location… moves the whole sync space to a different storage location. You can also use it to switch between encrypted and plain text, since the encryption mode cannot be changed in place.

1. Enter the target location. It must be a brand-new, dedicated, empty location; a location that is not empty cannot be used.
2. Choose the encryption of the target: keep the current mode, change to end-to-end encryption, or change to no encryption. You can tick Replace the master key. When the target is the CiteDesk Sync Service and stays end-to-end encrypted, you can also choose the Key custody: kept by you, or kept by CiteDesk.
3. Click Check and Plan; when you see the amount of data, click Start Transfer.
4. The process runs in stages: Planned, Sealing the source, Copying, Verifying, Publishing to the target, Switching, Done. It can be interrupted and continued later with Resume Transfer, or you can Abort Transfer….

Good to know:

• When the plan is made, the window lists notes about this transfer: other devices must reconnect; the source is kept as an archive; the old credentials stay valid at your storage provider; a new recovery code is required; the target is not encrypted; CiteDesk keeps the key of the target (the operator of the server can decrypt it); moving from custody to a key kept by you requires a new master key; how long it takes depends on the network and the storage service. For a CiteDesk Sync Service target, conditional writes are not probed while planning; the target is checked for availability and emptiness when the transfer starts.
• Replace the master key produces a new recovery code, which appears in a window after you start the transfer, and which you must save and confirm before the transfer continues; the old recovery code no longer works for the new location. This is the only way to make a leaked old recovery code useless.
• During the transfer the source location is sealed and kept as an archive; it is not deleted. Current data moves to the new location together with the history that is still within the retention period and can be read back without gaps from the current version; older or unreadable history stays in the archive and is not carried over.
• The target can also be the sync service the space is already on (to change the encryption, who keeps the key, or to replace the master key). At least one of these must change, otherwise the window does not allow planning. The old copy stays as an archive: read-only, still counted against your usage, and marked as such on the Sync spaces page of User Center. An archive is never deleted automatically; only you can start Delete the old copy in User Center (it asks for your password and can be undone for 14 days). A device that has not reconnected cannot do so after the deletion, so reconnect those devices first.
• After a transfer to your own storage, the sealed old copy on the official service can also be deleted in the User Center, on the same terms as an archive: it asks for your password, can be undone for 14 days, and frees its space only when that ends; a device that has not reconnected to the new location cannot do so after the deletion.
• Sealing is effective only against devices that follow the protocol. To keep the old location from being written to at all, revoke the old credentials or make it read-only at your storage provider; this may take a while to take effect.
• Your other devices must reconnect and confirm the new location: their sync settings show Rebind to the New Location, where you enter the new location's details, and the changes on that device not yet uploaded are kept. Changes not yet uploaded on a device that never comes online again cannot be recovered.
• After a transfer to a target without encryption, your research content there is readable plain text.
• Changing who keeps the key always replaces the master key; CiteDesk enforces this and it cannot be turned off. From a key kept by you to custody: the target is a new space on the CiteDesk Sync Service, and before the source is sealed the new key is deposited on the server; if that fails the transfer stays at the planning stage and the source is not sealed. Your account must already have an authenticator bound; if it does not, you are told so and offered a shortcut to the authenticator page. From custody to a key kept by you: the target can be your own storage (S3 or WebDAV) or the same sync service. When the transfer completes, the server deletes the old key it kept for this space; until then the server can still decrypt the source archive, and deleting it does not change that the server once knew the key, which is why a new key is required.

Disconnecting#

After Disconnect…, this device no longer syncs. The library and workspace files on this device are not touched at all, and neither is the remote data; changes not yet uploaded stay on this device. You can also tick the option to remove the credentials this device saved for the space.

To join an existing space again later, the library on this device must be empty; see Creating and joining a space.