---
title: Vault Git Sync — Architecture & Scripts
updated: '2026-06-02'
type: tech
tags:
  - 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)

```bash
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

```bash
# 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.

```bash
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.