Sync taskledger state across PCs

Taskledger already supports keeping durable task state outside the source repository. The recommended workflow is to commit only taskledger.toml in the source repo, point taskledger_dir at an external sibling directory, and sync that external directory with a private Git repository.

External state directory

Use taskledger init --taskledger-dir or edit taskledger.toml so the workspace keeps only config while the durable state lives elsewhere:

config_version = 2
taskledger_dir = "../taskledger-state/project-a"
project_uuid = "keep-existing-uuid"
project_name = "project-a"
ledger_ref = "main"

Relative paths are preferred because they keep the same sibling layout working across multiple PCs.

Private state Git repo

Recommended layout:

/home/me/src/project-a/                  # source repo
/home/me/src/taskledger-state/           # private state repo
/home/me/src/taskledger-state/project-a/
  storage.yaml
  ledgers/
    main/
      tasks/
      events/
      releases/
      indexes/

The source repository keeps taskledger.toml and ignores .taskledger/. The private state repository stores the external taskledger_dir contents.

Second PC bootstrap

Clone both repositories as siblings:

cd ~/src
git clone <source-repo-url> project-a
git clone <private-state-repo-url> taskledger-state

cd project-a
taskledger status --full
taskledger doctor
taskledger task list

Daily sync protocol

Taskledger provides a Git sync command group that supports this workflow:

taskledger sync git init --repo ../taskledger-state --project-path project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git push
taskledger sync git push --message "Sync project-a taskledger state"

In a shared taskledger-state repository, Taskledger can safely inspect and report project-local vs outside-project dirty paths. sync git push commits repository-wide changes by design to match the standard Git workflow. Use sync git cd for advanced manual inspection or conflict resolution.

For manual conflict resolution or debugging:

cd "$(taskledger sync git cd)"
git status --short

Before starting work on a PC:

cd ~/src/project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git import-local
taskledger doctor
taskledger next-action

After finishing a task cycle or stopping at a safe boundary:

cd ~/src/project-a
taskledger doctor
taskledger sync git status
taskledger sync git push

Active lock rule

Do not use the same Taskledger state concurrently from multiple PCs. Prefer to switch machines only when:

  • the task is done;

  • the task is approved and no implementation lock exists;

  • implementation is finished and validation has not started; or

  • no active lock is present.

Keep one active writer per project. Concurrent writes can produce Git conflicts or semantic conflicts across canonical task records.

When to use export/import instead

Archive commands are still the transfer primitive and remain available at both the root and under sync:

taskledger export task-0040
taskledger import ./taskledger-task-project-a-main-task-0040-...tar.gz
taskledger sync export --output ./taskledger-transfer.tar.gz
taskledger sync import ./taskledger-transfer.tar.gz --dry-run

If work must move mid-run, prefer task-scoped transfer archives instead of syncing the full live state directory:

taskledger export task-0040
# copy archive to the other PC
taskledger import ./taskledger-task-project-a-main-task-0040-...tar.gz
taskledger next-action
taskledger implement resume --reason "Continue imported implementation."

Imported runtime locks are quarantined by default, which makes archive transfer safer than syncing an active lock between machines.

Syncthing/rclone caveats

Syncthing and rclone bisync can transport the external state directory, but Git is the safer default for Taskledger’s text-first state because it preserves history and exposes conflicts directly.

If Syncthing is used:

  • avoid concurrent writers;

  • stop one agent before starting another PC;

  • run taskledger doctor after sync; and

  • resolve conflict files before continuing.

Treat rclone bisync as an advanced workflow. Keep Git push/pull under user control and do not automate network sync from Taskledger itself.