Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · App internals

Settings export, import and backup

On this page
  1. File format
  2. Secrets
  3. Import in two phases
  4. Automatic backup and restore
  5. Limits and errors
  6. Test IDs

Gitoodo can write its settings to a JSON file, read them back on another machine or after a reinstall, and undo the last import from an automatic backup. The UI lives in Settings → Backup (src/views/settings/BackupPage.tsx); the logic is in crates/core/src/store/transfer.rs and the Tauri commands in src-tauri/src/transfer.rs.

File format#

{ "app": "gitoodo", "schema_version": 2, "settings": { "...": "..." } }
FieldMeaning
appAlways gitoodo; any other value is rejected as a foreign file.
schema_versionSettings schema the file was written with.
settingsThe stored settings, accounts included, without any secret value.
  • Older files are migrated in memory on import; the preview says so.
  • Files from a newer schema are refused instead of being guessed at.
  • The export is written atomically, so an interrupted export never leaves a half file behind.
  • Suggested file name: gitoodo-settings-YYYY-MM-DD.json (local date).

Secrets#

Tokens and the chat webhook URL live only in the keychain and never appear in an export, a backup, a preview or a log line. After an import, accounts whose token is missing in this machine's keychain show a "renew token" action (accounts_needing_token).

The usage statistics choice and its random install ID live in usage.json, not in the settings, so they are never exported, imported or backed up: an imported settings file leaves the statistics undecided on the new machine, and a restored backup never brings back an install ID that was deleted by switching the statistics off (docs/privacy.md, "Usage statistics").

Import in two phases#

  1. Preview (preview_settings_import): the file is read, validated and migrated without changing anything. The preview lists the names of changed settings (never their values), added and removed accounts, accounts without a token and whether a migration ran.
  2. Apply (import_settings): after the user confirms, the current settings are written to the backup first, under the settings lock. If the backup fails, nothing is replaced. Then the imported settings are saved and theme, global shortcut and sync loops restart with them.

Validation beyond the field types: every account needs a non-empty, unique id, a login and an http(s) address with a host.

Automatic backup and restore#

  • Every import writes the previous settings to settings.backup.json next to the settings file.
  • settings_backup_time returns the backup's time (Unix ms) or nothing; the UI shows it or a "no backup" hint.
  • restore_settings_backup backs up the current settings before restoring, so a restore can itself be undone.

Limits and errors#

ReasonWhen
too_largeFile over 1 MiB; it is refused without reading.
not_jsonNot valid JSON.
foreign_fileapp is not gitoodo.
newer_versionSchema newer than this build supports.
invalid_contentValidation failed; detail capped at 200 chars.
no_backupRestore without a backup.
ioFile access or encoding failed.

The frontend maps these to its own rejection keys (rejection() in src/views/settings/transfer.ts) and shows a calm, localised message. Import, export and restore are recorded as audit events without content.

Test IDs#

settings-backup-export, -import, -preview, -preview-migrated, -confirm, -confirm-yes, -cancel, -status, -renew, -restore, -restore-none, -restore-time, -restore-open (all prefixed settings-backup).

Docs version: dev