Quick Start

Follow along in your terminal. Every command below shows what you’ll see.

Create a test dataset

mkdir -p ~/gda-test/sub-01/meg ~/gda-test/sub-01/beh
cd ~/gda-test
echo "simulated MEG recording" > sub-01/meg/run.fif
echo "trial,rt,accuracy" > sub-01/beh/data.csv
echo "1,450,1" >> sub-01/beh/data.csv
echo "2,520,0" >> sub-01/beh/data.csv

1. Initialize

gda init

Output:

Initialized GDA store in .gda
Store: .gda
Index: 0 entries

This creates a .gda/ directory. It’s where GDA stores everything.

2. Add data

gda add sub-01/

Output:

Added sub-01/meg/run.fif (21 B, SHA256: a1b2c3d4e5f6...)
Added sub-01/beh/data.csv (39 B, SHA256: f6e5d4c3b2a1...)

GDA hashes each file (SHA256), stores it in .gda/objects/, and replaces the original with a symlink pointing to the object.

3. Check status

gda status

Output:

Tracked files:
  ok  21 B   sub-01/meg/run.fif
  ok  39 B   sub-01/beh/data.csv

2 files, 60 B total

Every file shows ok if everything’s intact.

4. Create a snapshot

gda snapshot raw-v1

Output:

Snapshot "raw-v1" saved (2 files, 60 B)

A snapshot records every tracked file’s path and hash. Think of it as a bookmark you can return to.

5. View history

gda log

Output:

  raw-v1  2026-06-05 12:30:00  2 files  60 B

All your snapshots, with timestamps and sizes.

6. Modify and snapshot again

gda unlock sub-01/beh/data.csv
echo "3,380,1" >> sub-01/beh/data.csv
gda lock sub-01/beh/data.csv
gda snapshot raw-v2
gda log

Output:

Unlocked sub-01/beh/data.csv
Locked sub-01/beh/data.csv
Snapshot "raw-v2" saved (2 files, 70 B)
  raw-v2  2026-06-05 12:31:00  2 files  70 B
  raw-v1  2026-06-05 12:30:00  2 files  60 B

7. Restore a previous state

gda checkout raw-v1
gda status

Output:

Restored "raw-v1" (2 files)
Tracked files:
  ok  21 B   sub-01/meg/run.fif
  ok  39 B   sub-01/beh/data.csv

Your project folder is back to exactly how it was after raw-v1. The data from raw-v2 is still in the store — you can switch back any time.

What’s next?

→ Adding Data — track real datasets, handle directories → Snapshots & Checkout — version management workflow → Commands — full command reference