← Contents

Data Directory and Backups

CiteDesk keeps the library and its attachments in a data directory. Knowing where it is and what is in it lets you back up and move your data with confidence.

Where the data directory is

By default the data directory is the application's configuration directory. Help > Open Data Folder opens it in Finder (or the system's file manager). It mainly contains:

  • the library database (a SQLite file), which holds references, collections, tags, notes and annotations;
  • the storage directory: attachment files stored in the library, one subdirectory per attachment;
  • the styles directory: the styles you imported;
  • the backups directory: automatic backups of the database;
  • caches that can be rebuilt, such as the full-text index.

Documents themselves (the Markdown files) are not in the data directory; they are in the workspace folder you opened.

Under Settings > Advanced > Data Directory Location you can switch to a custom location or reset to the default. Changing the location does not move any data. After the change the application asks you to quit; move the whole data directory to the new location yourself while the application is closed, then start it again. CiteDesk does not modify the files in the old location.

At startup, if the configured location cannot be found (an external disk is not connected, for example), the application asks you first: use the default location, choose a location again, or quit. It never quietly creates an empty library.

A data directory in a cloud folder

Do not put the data directory in a synchronized folder such as Dropbox, iCloud, OneDrive or Google Drive. The database is read and written frequently by the database engine, and synchronization software that copies or locks files in between may corrupt the database, lose data, or leave you with several conflicting copies of the same data.

If the application detects that the data directory is in such a folder, it warns you at startup and offers: choose another place, leave it, and "Do not show this warning again". To keep a library in step on several computers, use the application's own Sync, not synchronization of the data directory.

When you choose a custom location, the same warning appears if the chosen folder is in a cloud folder.

Automatic backups

The application backs up the database to the backups directory of the data directory from time to time, keeping a few copies in rotation. The number of copies and the interval are decided by two settings, backupNumBackups (2 copies by default) and backupIntervalMinutes (1440 minutes, one day, by default); fewer than 1 copy means no backups; you can change them in the settings editor at the bottom of the Advanced page. Nothing is backed up again if nothing has changed, and a backup is always forced before references are merged. If a backup cannot be written it is only logged and never blocks your work.

A backup contains only the database, not the attachment files. For a complete backup, copy the whole data directory while the application is closed.

Restoring from a backup

When the database cannot be opened or fails its check, a banner at the top of the library page says that it cannot be read, and saving is locked so that damaged data is not damaged further. When a usable automatic backup exists, the banner has "Restore from Automatic Backup": the application first checks that the backup can be read and that its version is understood, moves the damaged database into the backups directory marked .damaged (it is not deleted), and then puts the backup in place. A restore loses the changes made after the backup, so be sure before you confirm.

If there is no usable backup, try to repair the database with SQLite tools while the application is closed, or ask someone who can help. For more cases see Troubleshooting.

The database is in use

The database is opened exclusively. If the same data directory is already open in another CiteDesk (or another program), the application says that the database of the data directory is in use and quits without opening it. Close the other instance first and start again.