For developers · App internals
Settings export, import and backup
On this page
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": { "...": "..." } }| Field | Meaning |
|---|---|
app | Always gitoodo; any other value is rejected as a foreign file. |
schema_version | Settings schema the file was written with. |
settings | The 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#
- 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. - 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.jsonnext to the settings file. settings_backup_timereturns the backup's time (Unix ms) or nothing; the UI shows it or a "no backup" hint.restore_settings_backupbacks up the current settings before restoring, so a restore can itself be undone.
Limits and errors#
| Reason | When |
|---|---|
too_large | File over 1 MiB; it is refused without reading. |
not_json | Not valid JSON. |
foreign_file | app is not gitoodo. |
newer_version | Schema newer than this build supports. |
invalid_content | Validation failed; detail capped at 200 chars. |
no_backup | Restore without a backup. |
io | File 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).