From 4e73647511b69986b1970f679adc605ed150fe6b Mon Sep 17 00:00:00 2001
From: Alexey Martemyanov <mallexxx@gmail.com>
Date: Sat, 23 May 2026 11:15:24 +0600
Subject: [PATCH] =?UTF-8?q?[2026-05-23]=20wiki:=20vault-git-sync=20doc=20?=
 =?UTF-8?q?=E2=80=94=20sync=20strategy,=20Taiga=20fix,=20incident=20log?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 wiki/tech/vault-git-sync.md | 94 +++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 wiki/tech/vault-git-sync.md

diff --git a/wiki/tech/vault-git-sync.md b/wiki/tech/vault-git-sync.md
new file mode 100644
index 00000000..03031930
--- /dev/null
+++ b/wiki/tech/vault-git-sync.md
@@ -0,0 +1,94 @@
+---
+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)
+```