Skip to content

Sync Usage#

Installation#

pip install capturegraph-sync

Basic Usage#

Sync a target to your local machine:

capturegraph-sync https://capture-graph.org/ --target "Clementime" --output ./data

This:

  1. Connects to the CaptureGraph server
  2. Fetches the target's manifest
  3. Downloads new/changed files to ./data/Clementime/
  4. Skips unchanged files

Command-Line Options#

capturegraph-sync [SERVER_URL] [OPTIONS]
Option Description
--target NAME Target name to sync
--output PATH Local output directory
--force Re-download all files
--dry-run Show what would be synced

Hash Store#

Sync maintains a local hash store at .capturegraph_sync.json inside each target's output directory:

./data/MyPlant/
├── .capturegraph_sync.json  ← Hash store
├── sessions/
│   └── daily/
│       └── .../
└── reference.heic

This allows:

  • Resumable syncs: Interrupted downloads continue where they left off
  • Change detection: Only download files that differ from server
  • Re-download verification: If a local file is deleted, sync re-downloads it

Sync Workflow#

Initial Sync#

capturegraph-sync https://capture-graph.org/ --target "Clementime" --output ./data

Output:

Syncing target: Clementime
  ↓ manifest.json
  ↓ reference.heic (2.3 MB)
  ↓ sessions/daily/00063B40.../photo.heic (4.1 MB)
  ↓ sessions/daily/00063B40.../notes.json (128 B)
  ...

Sync complete:
  Files downloaded: 24
  Files skipped: 0
  Total bytes: 98.2 MB

Incremental Sync#

capturegraph-sync https://capture-graph.org/ --target "Clementime" --output ./data

Output:

Syncing target: Clementime
  ✓ manifest.json (unchanged)
  ✓ reference.heic (unchanged)
  ✓ sessions/daily/00063B40.../photo.heic (unchanged)
  ↓ sessions/daily/00063B41.../photo.heic (4.2 MB)  ← New session
  ↓ sessions/daily/00063B41.../notes.json (156 B)
  ...

Sync complete:
  Files downloaded: 3
  Files skipped: 21
  Total bytes: 4.4 MB

Force Re-sync#

capturegraph-sync https://capture-graph.org/ --target "Clementime" --output ./data --force

Downloads all files regardless of hash comparison.

Working with Synced Data#

After syncing, use the Data Framework to load:

import capturegraph.data as cg

target = cg.CaptureTarget("./research_data/FieldStudy")
sessions = target.sessions.daily

for session in sessions:
    print(f"{session.date}: {session.notes}")

Troubleshooting#

Connection Errors#

Error: Unable to connect to server
  • Check your network connection
  • Verify server URL in config
  • Ensure server is running

Hash Mismatch#

Warning: Hash mismatch for file.heic, re-downloading

This is normal—the file changed on the server. Sync automatically re-downloads.

Missing Files#

Warning: File photo.heic missing locally, re-downloading

If you delete a local file, sync detects it and re-downloads.

See Also#