Git Sync

Git Sync

Sync your Obsidian vault across every device using your own free private GitHub repo.
No subscription. No cloud fees. Works on desktop (Windows / macOS / Linux) and mobile (iOS / Android).

---

How It Works

Your GitHub Account
        │
        ├── obsidian-personal-notes  ← Vault 1 (all your devices sync here)
        ├── obsidian-work-notes      ← Vault 2 (separate repo, same account)
        └── obsidian-research        ← Vault 3 (separate repo, same account)

Desktop  ──┐
Mobile   ──┼──▶  obsidian-personal-notes  (same private GitHub repo)
Laptop   ──┘

1. You connect your GitHub account once (in-browser, one approval click).
2. The plugin auto-creates a private repo named after your vault.
3. Every file save is automatically committed and pushed in the background.
4. Every device pulls the latest changes when Obsidian opens.
5. Conflicts are detected and shown with a side-by-side UI to resolve.

---

Features

• Works on all devices — desktop and mobile via isomorphic-git (pure JS, no native binary)
• One GitHub account, multiple vaults — each vault gets its own private repo
• Auto-sync — changes push silently in the background after a short debounce
• Pull on open — always up-to-date when you open Obsidian
• Conflict resolution UI — side-by-side view when two devices edit the same file
• Zero cost — uses your own free GitHub repos, no server involved
• No data leaves your account — all files go into your own private GitHub repo

---

Requirements

• Obsidian 1.0.0 or later
• A free GitHub account — sign up at github.com if you don't have one
• Internet access for sync (offline edits are queued and synced when back online)
• Node.js 18+ and npm (for building from source)

---

Part 1 — Developer Setup (Build from Source)

Prerequisites

1.1 — Clone the Repository

git clone https://github.com/livan116/github-valut-sync.git
cd github-valut-sync

1.2 — Install Dependencies

npm install

This installs:

• isomorphic-git — pure-JS git engine (works on mobile, no native binaries)
• esbuild — fast bundler
• typescript — type checker
• obsidian — type definitions only (not bundled)

1.3 — Register a GitHub OAuth App

You need to register a free OAuth App so users can log in with their GitHub account. This is done once — the client_id is then baked into the plugin code.

1. Go to github.com/settings/developers

2. Click OAuth Apps → New OAuth App

3. Fill in the form:

   Field	Value
   Application name	GitHub Vault Sync
   Homepage URL	https://github.com/livan116/github-valut-sync
   Authorization callback URL	https://obsidian.md (placeholder — Device Flow doesn't use this)

4. Click Register application

5. Copy the Client ID (looks like Ov23li...)

6. Copy .env.example to .env and set your Client ID:

   CLIENT_ID=Ov23liYOUR_ACTUAL_ID
   

Do not generate a Client Secret — Device Flow doesn't need it and secrets must never be embedded in plugin code.

1.4 — Build the Plugin

# Development build (watch mode — rebuilds on every save)
npm run dev

# Production build (minified, no source maps)
npm run build

Both commands output a single main.js file in the project root.

Watch mode (npm run dev) keeps running and rebuilds automatically as you edit source files. Leave it running while you test in Obsidian.

1.5 — Project Structure

github-valut-sync/
├── src/
│   ├── main.ts                   # Plugin entry point — wires everything together
│   ├── types.ts                  # All TypeScript interfaces & types
│   ├── constants.ts              # App-wide constants (CLIENT_ID injected here at build)
│   ├── auth/
│   │   └── github-device.ts      # GitHub OAuth Device Flow (no server needed)
│   ├── github/
│   │   └── api.ts                # GitHub REST API wrapper (create repo, get user)
│   ├── sync/
│   │   ├── fs-adapter.ts         # Bridges Obsidian DataAdapter → isomorphic-git fs
│   │   ├── git-sync.ts           # Core git operations: init / clone / pull / push
│   │   ├── queue.ts              # Debounced sync queue with mutex (no race conditions)
│   │   └── conflict.ts           # Conflict diff summary helper
│   └── ui/
│       ├── settings-tab.ts       # Plugin settings page
│       ├── conflict-modal.ts     # Side-by-side conflict resolution modal
│       └── status-bar.ts         # Live sync indicator in the status bar
├── .env                          # Local secrets — git-ignored, never committed
├── .env.example                  # Template — copy to .env and fill in CLIENT_ID
├── manifest.json                 # Obsidian plugin manifest
├── package.json
├── tsconfig.json
├── esbuild.config.mjs
└── main.js                       # Built output (git-ignored, generated by build)

---

Part 2 — Installing the Plugin

Option A — Manual Install from Build Output

After running npm run build:

1. Create the plugin folder inside your vault:

   YourVault/.obsidian/plugins/github-vault-sync/
   

2. Copy these two files into that folder:

   main.js
   manifest.json
   

3. Open Obsidian → Settings → Community plugins
4. Turn off Restricted Mode if prompted
5. Find GitHub Vault Sync in the list → toggle it ON

Tip for development: You can symlink the project directory directly into your vault's plugins folder so the built main.js is picked up automatically after each build:

# Windows (run as Administrator)
mklink /D "C:\path\to\vault\.obsidian\plugins\github-vault-sync" "C:\path\to\github-valut-sync"

# macOS / Linux
ln -s /path/to/github-valut-sync /path/to/vault/.obsidian/plugins/github-vault-sync

Option B — BRAT (Beta Testers)

1. Install the BRAT plugin from Community Plugins.
2. Open BRAT settings → Add Beta Plugin
3. Paste the repo URL: https://github.com/livan116/github-valut-sync
4. Click Add Plugin — BRAT installs it automatically.

---

Part 3 — Connecting Your GitHub Account

Do this on every device where you want sync. Use the same GitHub account each time.

Step 1 — Open Plugin Settings

Go to Settings → GitHub Vault Sync (scroll down in the left sidebar under Community Plugins).

Step 2 — Click "Connect GitHub"

You will see a screen like this:

┌─────────────────────────────────────────┐
│  Open this URL in your browser:         │
│  https://github.com/login/device        │
│                                         │
│           AB12-CD34                     │
│                                         │
│  Waiting for approval in browser…       │
└─────────────────────────────────────────┘

Your browser will open automatically. If it doesn't, copy the URL manually.

Step 3 — Enter the Code in Your Browser

1. The GitHub page asks: "Enter the code shown in your app"
2. Type in the 8-character code (e.g. AB12-CD34)
3. Click Continue
4. Review what access the plugin requests: private repos (to create and sync your vault repo)
5. Click Authorize

Step 4 — Done

Back in Obsidian you'll see:

Connected as @your-github-username. Vault syncing started!

The plugin will:

• First device: Create a new private repo named obsidian-<your-vault-name> and push all your files.
• Additional devices: Detect the existing repo and clone it automatically.

---

Part 4 — Using the Plugin

Automatic Sync

Once connected, the plugin runs silently in the background:

Status Bar

The bottom-right corner shows the current sync state:

Click the status bar item to trigger an immediate manual sync at any time.

Manual Sync

• Click the status bar item, or
• Open the Command Palette (Ctrl/Cmd + P) → search "MultiSync: Sync vault now"

---

Part 5 — Resolving Conflicts

A conflict happens when the same file is edited on two devices before either has synced.

When the plugin detects a conflict, a modal appears automatically:

┌──────────────────────────────────────────────────┐
│  Sync Conflict (1 / 2)                           │
│  File: notes/daily/2025-06-01.md                 │
│                                                  │
│  Changed lines:                                  │
│  Line 4:                                         │
│    - meeting at 3pm                              │
│    + meeting at 4pm                              │
│                                                  │
│  YOUR VERSION        │  REMOTE VERSION           │
│  ──────────────────  │  ─────────────────        │
│  # June 1            │  # June 1                 │
│  meeting at 3pm      │  meeting at 4pm           │
│                                                  │
│  [Keep Mine]  [Keep Theirs]  [Open in Editor]    │
└──────────────────────────────────────────────────┘

After resolving, the file is immediately committed and pushed.

---

Part 6 — Multiple Vaults

Each vault gets its own separate repo automatically. There's nothing extra to configure.

Vault: "Personal Notes"   →  github.com/you/obsidian-personal-notes
Vault: "Work"             →  github.com/you/obsidian-work
Vault: "Research"         →  github.com/you/obsidian-research

On each device:

1. Open the vault in Obsidian.
2. Go to Settings → GitHub Vault Sync → connect your GitHub account.
3. The plugin detects which vault is open and connects to the right repo automatically.

---

Part 7 — Settings Reference

Default Excluded Patterns

.obsidian/workspace
.obsidian/workspace.json
.obsidian/plugins/*/data.json

These are excluded because they change frequently, are device-specific, and don't need to be shared.

To add more exclusions, open Settings → GitHub Vault Sync → Excluded patterns and add one pattern per line. Wildcards (*) are supported.

Example — exclude all files in a Private folder:

Private/*

---

Troubleshooting

"Device code expired"

The 8-character code has a 15-minute expiry. Click Connect GitHub again to get a fresh code.

"Access denied"

You clicked Cancel on the GitHub authorization page. Click Connect GitHub to try again.

Sync shows ✗ Sync Error

1. Check your internet connection.
2. Open Settings → GitHub Vault Sync — if disconnected, click Connect GitHub to re-authenticate.
3. GitHub tokens occasionally expire — reconnecting issues a fresh token.

Files not appearing on second device

1. Make sure you connected the same GitHub account on both devices.
2. Check the status bar on both devices — both should show ✓ MultiSync.
3. Trigger a manual sync on the device that has the new files (Ctrl/Cmd + P → "Sync vault now").

Mobile — "Cannot sync"

• Ensure your mobile device has an internet connection.
• The plugin uses Obsidian's built-in HTTP layer so it does not need special mobile permissions.
• If syncing fails on mobile, try disconnecting and reconnecting your GitHub account.

.git folder visible in vault

The .git folder is hidden in Obsidian by default. If you see it, go to
Settings → Files & Links → Excluded files and add .git.

Build fails with "Cannot find module 'obsidian'"

Run npm install to install devDependencies. The obsidian package provides types only.

Build warns "CLIENT_ID is not set"

Copy .env.example to .env and fill in your GitHub OAuth App Client ID.

TypeScript errors after pulling

Run npm install — a dependency may have been added. Then re-run npm run build.

---

FAQ

Q: Is my data private?
A: Yes. The plugin creates a private GitHub repo. Only your GitHub account can access it.

Q: Does the plugin developer see my notes?
A: No. The plugin runs entirely on your device and connects directly to your own GitHub account. There is no intermediate server.

Q: What happens if I edit the same file on two offline devices?
A: When both devices come online, the plugin detects the conflict and shows you the resolution modal.

Q: Can I use this with an existing vault that already has files?
A: Yes. On first connection, the plugin pushes all your existing files to the new GitHub repo.

Q: Does this work with Obsidian's built-in sync?
A: It's designed to replace, not complement, Obsidian Sync. Using both at once is not recommended as they may conflict.

Q: What is the storage limit?
A: GitHub repos have a soft limit of 1 GB per repo. A typical Obsidian vault of markdown files is well under 100 MB.

Q: Can I view my notes on GitHub directly?
A: Yes — GitHub renders Markdown files beautifully. Browse your private repo at github.com/your-github-username/obsidian-<vaultname>.

Q: Why does the plugin need the repo OAuth scope?
A: The repo scope is the minimum required to create and push to private repositories. Without it GitHub only allows access to public repos.

---

Privacy & Security

• Your GitHub access token is stored only in Obsidian's local plugin data folder (.obsidian/plugins/github-vault-sync/data.json) on each device. It never leaves your device except to communicate directly with GitHub's API.
• The plugin requests only the repo scope — the minimum required to create and access private repositories.
• To revoke access at any time: GitHub → Settings → Applications → Authorized OAuth Apps → Revoke.

---

Architecture Notes (for Contributors)

Key constraints:

• Never use require('fs') — always use the fs-adapter so mobile works.
• Always pull before push — enforced in git-sync.ts::sync().
• Always use requestUrl from obsidian for HTTP — never fetch or axios.
• Never store the GitHub token anywhere other than this.saveData().

---

Contributing

Pull requests welcome!

# 1. Fork and clone
git clone https://github.com/livan116/github-valut-sync.git
cd github-valut-sync

# 2. Install deps
npm install

# 3. Copy .env.example to .env and set your CLIENT_ID
cp .env.example .env

# 4. Start watch mode
npm run dev

# 5. Symlink into your test vault (see Part 2 above)
# 6. Make your changes — Obsidian hot-reloads the plugin automatically
# 7. Run a type check before submitting
npx tsc --noEmit

For bugs and feature requests, open an issue.

---

License

MIT © 2025 Livan Kumar