---
title: Vault Git Sync — Setup & Pitfalls
created: '2026-05-23'
updated: '2026-05-23'
type: tech
namespace: wiki
tags: [vault, git, sync, infra, obsidian]
---

# Vault Git Sync

Obsidian vault is a bare git repo on TrueNAS (`mallexxx.duckdns.org:/mnt/RED_2TB/storage/git/obsidian-vault.git`).
Three hosts sync to it: Eagle, Kraken, Taiga.

## Sync Strategy (correct)

All hosts must follow this order:

```
1. stash local changes       (git stash)
2. pull from remote          (git fetch + git merge)
3. pop stash                 (git stash pop)
4. commit if anything new    (git add -A + git commit)
5. push                      (git push)
```

**Why this order matters:** `git add -A` before pull stages deletions of files
that exist on remote but not locally. This caused Taiga to delete 32+ wiki files
on 2026-05-23 (two incidents: 3a44a55, c9020c4).

## Scripts

| Host   | Script                             | Status         |
|--------|------------------------------------|----------------|
| Eagle  | `~/scripts/sync-vault.sh`          | ✅ Correct      |
| Kraken | `~/scripts/sync-vault-partial.sh`  | ✅ Correct      |
| Taiga  | `/opt/data/sync-vault.sh`          | ❌ **BROKEN** — see below |

The correct script for Taiga/Kraken is at `~/scripts/sync-vault-partial.sh` on Eagle.
It uses sparse checkout (only `personal/` and `family/`), which is an additional safeguard:
if Taiga never checks out `wiki/`, it can never delete wiki/ files even if the script has bugs.

## Taiga Fix (TODO)

Taiga runs TrueNAS. The broken script is at `/opt/data/sync-vault.sh`.

To fix (requires TrueNAS console or web UI → System → Advanced → Init/Shutdown Scripts):

1. Copy correct script from Eagle:
   ```bash
   scp ~/scripts/sync-vault-partial.sh root@<taiga-ip>:/opt/data/sync-vault.sh
   ```
2. On Taiga, ensure vault uses sparse checkout:
   ```bash
   cd /path/to/obsidian-vault
   git config core.sparseCheckout true
   echo "personal/" > .git/info/sparse-checkout
   echo "family/" >> .git/info/sparse-checkout
   git read-tree -mu HEAD
   ```
3. Test: `bash /opt/data/sync-vault.sh`

## .gitignore

Plugin binaries are excluded to prevent cross-device obsidian-git version conflicts:

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

Each device manages its own plugin binaries via Obsidian's built-in update mechanism.
`data.json` (plugin config) IS tracked — shared settings across devices.

## Incident: 2026-05-23

**Root cause:** Taiga's `/opt/data/sync-vault.sh` did `git add -A` before `git pull`.

**Sequence:**
- 22:02 UTC Eagle created 15 wiki files (d757029, 6dc4b89)
- 00:00 UTC Taiga ran sync → staged deletions (local didn't have wiki/) → commit 3a44a55
- 03:02 UTC Taiga ran again → deleted 8 more files (c9020c4)

**Recovery:** `git checkout <hash> -- <file>` for each file from last-good commits.
32 files restored in commit 620e2df.

## Stash Cleanup

Orphaned stashes from obsidian-git mobile syncs accumulate. Safe to drop:
```bash
git stash drop stash@{N}  # drop specific, or:
git stash clear            # drop all (only if no unrecovered work)
```