obsidian-vault/family/how-to/vault-git-sync.md

title, updated, type, tags

title	updated	type	tags
Vault Git Sync — Architecture & Scripts	2026-06-02	tech	vault git sync infra obsidian

Vault Git Sync

Obsidian vault is a bare git repo on TrueNAS: /mnt/RED_2TB/storage/git/obsidian-vault.git Also mirrored in Gitea: https://git.mallexxx.duckdns.org/git_admin/obsidian-vault

Four clients sync to it: Eagle, Kraken, Taiga (vault), Taiga (syncthing/phone).

Architecture

bare repo (obsidian-vault.git) — source of truth
   ↑↓                ↑↓               ↑↓                    ↑↓
Eagle              Kraken         Taiga /vault         Taiga /obsidian-syncthing
full clone         sparse clone   sparse clone          full clone
~/obsidian         ~/obsidian     personal/family/      phone ↔ Syncthing
                   personal/family/  .obsidian/
                   .obsidian/

Taiga runs 3-phase sync (order matters):

1. syncthing → phone changes land in bare repo first
2. vault → agent (mcpvault) changes land in bare repo
3. syncthing → agent changes propagate to phone

Sync Algorithm (same for all clients)

git add -A && git commit          # commit local changes
git fetch origin main             # get remote state
git merge origin/main --no-edit   # 3-way merge (conflict → commit markers)
git push origin main              # push back

No stash. No GIT_DIR/GIT_WORK_TREE workarounds.

Scripts

Host	Script	Type	Trigger
Eagle	~/scripts/sync-vault.sh	full clone	Hermes cron */5
Kraken	~/scripts/sync-vault.sh	sparse clone	host crontab */5
Taiga	/opt/data/sync-vault.sh	3-phase orch.	Hermes cron */5

All clients share a common library: sync-vault-lib.sh (same dir as sync-vault.sh). Source of truth for scripts: ~/Developer/vault-sync-test/scripts/ on Eagle.

Taiga Container Mounts

Container path	Host path	Purpose
/vault	/mnt/RED_2TB/storage/obsidian	sparse clone (agent rw)
/vault.git	/mnt/RED_2TB/storage/git/obsidian-vault.git	bare repo (git remote)
/obsidian-syncthing	/mnt/RED_2TB/storage/obsidian-syncthing	full clone (phone sync)
/opt/data	/mnt/RED_2TB/docker/hermes/config	Hermes config + scripts

/vault is a sparse clone with remote = file:///vault.git. /vault.git is hidden from the agent (mcpvault points to /vault).

Sparse Checkout Paths

Taiga and Kraken check out only:

personal/
family/
.obsidian/

work/ and wiki/ are never checked out on sparse clients — they never touch those paths.

Deploy a Script Fix

# Edit on Eagle:
~/Developer/vault-sync-test/scripts/sync-vault-lib.sh   # common algorithm
~/Developer/vault-sync-test/scripts/sync-vault.sh       # Taiga 3-phase orchestrator

# Deploy to Taiga:
scp ~/Developer/vault-sync-test/scripts/sync-vault-lib.sh \
    ~/Developer/vault-sync-test/scripts/sync-vault.sh \
    truenas_admin@mallexxx.duckdns.org:/mnt/RED_2TB/docker/hermes/config/

# Deploy to Kraken (via sudo):
cat ~/scripts/sync-vault-lib.sh | ssh kraken "sudo tee ~/scripts/sync-vault-lib.sh > /dev/null"
cat ~/scripts/sync-vault.sh     | ssh kraken "sudo tee ~/scripts/sync-vault.sh > /dev/null"

.gitignore

Plugin binaries excluded to avoid cross-device conflicts:

.obsidian/plugins/obsidian-git/main.js
.obsidian/plugins/obsidian-git/styles.css
.obsidian/plugins/obsidian-git/manifest.json

data.json (plugin config) is tracked — shared settings.

Regression Tests

~/Developer/vault-sync-test/test-sync.sh — 16 scenarios (A–P): covers Cyrillic filenames, moves, deletes, conflicts, work/ phantom-delete, 3-phase sync.

cd ~/Developer/vault-sync-test && bash test-sync.sh

Pitfalls

• git add pathspec fails with fatal: pathspec did not match any files when a directory doesn't exist on disk — use git add -A instead
• git add -A in sparse worktree still stages deletions of out-of-cone files tracked in index — need to unstage them (fixed in old script; irrelevant with proper clone)
• core.quotePath=true (default) escapes Cyrillic paths in git ls-files output — use -c core.quotePath=false
• ZFS on TrueNAS blocks chmod — git init fails from host; must run from inside Docker container or create .git structure manually

History

• 2026-05-23: Taiga deleted 32+ wiki files. Root cause: git add -A before merge staged deletions of files outside sparse cone. Fixed with scoped git add.
• 2026-06-01: "Керамика" lost from gift-ideas. Root cause: git add $SPARSE_PATHS failed silently when .obsidian/ absent — patch+move not committed.
• 2026-06-02: Full architecture migration. Taiga /vault converted from GIT_DIR=bare GIT_WORK_TREE workaround to proper sparse clone. All clients unified on same commit→fetch→merge→push algorithm. Sync interval: every 5 min.