Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Data, backups, and logs

Where data lives

PlatformDatabase
macOS~/Library/Application Support/productivity/tasks.sqlite3
Linux$XDG_DATA_HOME/productivity/tasks.sqlite3 (default ~/.local/share/…)

Set PRODUCTIVITY_DATA_DIR to use a separate workspace, for example for testing:

PRODUCTIVITY_DATA_DIR="$HOME/productivity-test" cargo run --locked

Backups

Quit the app, then copy tasks.sqlite3. When Notes is in use, back up the Markdown folder and .productivity-recovery together with the database: the note index can be rebuilt, but links and shortcuts cannot. Recovery copies are kept until you discard them.

Back up the database and the notes folder at the same time, while the app is closed, so links and shortcuts match the notes. Restoring only the Markdown folder brings back note content and IDs, but not links, shortcuts, or sorting. Rebuilding the index never restores them. Export all… in Notes copies Markdown and images only. It does not replace a backup of the database.

To delete everything the app stores, use Settings → Danger zone → Clear all data (Settings).

Run one app instance per database, and do not sync the live database through a file-sync service. If the database cannot be opened, the app exits with an error rather than replacing it.

Schema migrations

The database schema is versioned with SQLite’s user_version and migrated in one transaction at startup; a database from a newer version is refused. Every migration preserves existing tasks, projects, dependencies, and settings except explicitly retired preferences.

VersionChange
2Status replaces the completed flag (open → To do, completed → Done)
3–4Settings; only the task-list completion preference is kept
5–6Projects and dependencies; the abandoned related-link table is removed
7Per-view visibility, all shown
8Optional start dates
9Notes visibility, hidden
10–12Note index, associations, shortcuts, recovery journal, and a constraint repair
13–14Archiving and Today planning
15Compact design preference
16Task type, existing tasks become Task
17Appearance and color scheme preferences
18Calendar week-number preference, hidden by default
19Full/work-week display and configurable working days
20Today view visibility and timeboxes; retires List’s completed-visibility preference
21Saved Today workday start/end times, default 06:00–22:00
22UI font preference, System default unless chosen
23Task status history for Insights (existing tasks get a baseline entry) and Insights visibility, shown
24Today’s part of the day and manual order for planned tasks; existing plans become Anytime
25An optional web link per task, such as a Jira issue or GitLab merge request
26Merge request, Issue, and Jira task types (the task table is rebuilt; all data kept)
27Plans made ahead for tomorrow; existing plans keep counting today
28Kanban column order and hidden columns, defaulting to all four in status order

Logs

Logs go to stderr and to logs/ inside the data directory. Files rotate daily or at 2 MiB, and at most seven are kept. Set RUST_LOG to change verbosity (default warn,productivity=info):

RUST_LOG=warn,productivity=debug cargo run --locked

The log file, stderr, and Insights → Logs receive the same events: Productivity’s own and, so that problems inside libraries such as GPUI are visible too, the warnings and errors of its dependencies. Productivity’s own events contain no task titles, note contents, or paths, but dependency messages may include file paths or other details, and IDs and timings can be sensitive as well, so review logs before sharing them. The files are readable only by you.

Startup and shutdown timing

Each launch logs startup steps with elapsed_ms since the process started: data loaded, platform ready, window created (the window and GPU renderer exist), main window opened, and first frame drawn. Quitting logs quit requested with how it was asked (window close, title bar close, or the Quit action), then shutdown steps with elapsed_ms since that request: closing windows, releasing workspace, and event loop finished. The process still flushes the log and lets the graphics driver clean up after the last line, which no log can show.

To look at a slow start or exit of an installed app (for example from the APT package):

  1. Start it from a terminal, then close it as usual. The second command prints when the process really ended, in UTC like the log:

    productivity; date -u +%H:%M:%S.%N
    

    The gap between the event loop finished line and that time is spent after the log ends. To also log the graphics adapter GPUI chooses, start it with env RUST_LOG=info productivity instead.

  2. Read the newest file in ~/.local/share/productivity/logs/:

    grep -E "startup|shutdown|quit requested" \
      "$(ls -td ~/.local/share/productivity/logs/* | head -1)"
    
  3. When started from the application menu instead, stderr goes to the user journal: journalctl --user -b | grep -i productivity.

On laptops with two GPUs, also note the output of lspci | grep -iE 'vga|3d'.