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   ──┘

You connect your GitHub account once (in-browser, one approval click).
The plugin auto-creates a private repo named after your vault.
Every file save is automatically committed and pushed in the background.
Every device pulls the latest changes when Obsidian opens.
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

Tool	Version	Install
Node.js	18+	https://nodejs.org
npm	9+	Bundled with Node.js
Git	any	https://git-scm.com

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 definitions / optional type checking (not part of the build)
obsidian — type definitions only (not bundled)

1.3 — 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. There are no build-time secrets — the GitHub OAuth Client ID is entered by each user in plugin settings at runtime (see Part 3), so the build needs no .env or CI secret.

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

1.4 — 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 (URLs, branch, debounce)
│   ├── 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
├── 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:

Create the plugin folder inside your vault:

YourVault/.obsidian/plugins/git-obsi-sync/

Copy these two files into that folder:
```
main.js
manifest.json
```
Open Obsidian → Settings → Community plugins
Turn off Restricted Mode if prompted
Find Git 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\git-obsi-sync" "C:\path\to\github-valut-sync"

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

Option B — BRAT (Beta Testers)

Install the BRAT plugin from Community Plugins.
Open BRAT settings → Add Beta Plugin
Paste the repo URL: https://github.com/livan116/github-valut-sync
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 — Register a GitHub OAuth App (one-time)

The plugin authenticates through your own GitHub OAuth App — there is no shared/built-in app, so you register one once and reuse its Client ID on every device.

Go to github.com/settings/developers → OAuth Apps → New OAuth App.

Fill in:

Field	Value
Application name	Anything except a name containing "GitHub" (GitHub rejects those). It's just the label shown on the authorization screen.
Homepage URL	`https://obsidian.md` (any valid URL works)
Authorization callback URL	`https://obsidian.md` (placeholder — Device Flow doesn't use it)

Register application, then enable Device Flow on the app's settings page — the plugin will not work without it.
Copy the Client ID (looks like Ov23li…). Do not create a Client Secret — Device Flow doesn't need one.

Step 2 — Enter the Client ID in Obsidian

Go to Settings → Git Sync, paste your Client ID into GitHub OAuth Client ID.

Step 3 — 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 4 — Enter the Code in Your Browser

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

Step 5 — 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:

Event	What happens
You save / edit a file	Changes are committed and pushed after 3 seconds of inactivity
You open Obsidian	Latest changes are pulled from GitHub
You close Obsidian	Any pending changes are flushed and pushed
Two devices edit same file	Conflict modal appears next time you open Obsidian

Status Bar

The bottom-right corner shows the current sync state:

Indicator	Meaning
`✓ MultiSync`	All good, fully synced
`↓ Syncing…`	Pulling from GitHub
`↑ Syncing…`	Pushing to GitHub
`⚠ Conflict`	Two devices edited the same file — action needed
`✗ Sync Error`	Network or auth issue — hover for detail

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 "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]    │
└──────────────────────────────────────────────────┘

Button	Action
Keep Mine	Use the version from this device, discard remote changes
Keep Theirs	Use the remote version, discard local changes
Open in Editor	Close modal, open the file — edit it manually, then sync again

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:

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

Part 7 — Settings Reference

Setting	Default	Description
Auto-sync	On	Automatically sync on file changes
Sync debounce	3000 ms	How long to wait after your last keystroke before syncing
Excluded patterns	See below	Files/folders that will never be synced

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 → Git 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`

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

Files not appearing on second device

Make sure you connected the same GitHub account on both devices.
Check the status bar on both devices — both should show ✓ MultiSync.
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.

"Enter your GitHub OAuth App's Client ID before connecting"

You haven't set a Client ID yet. Register an OAuth App with Device Flow enabled (see Part 3 · Step 1) and paste its Client ID into Settings → Git Sync → GitHub OAuth 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/git-obsi-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)

Concern	Solution	Why
Auth	GitHub OAuth Device Flow	No server or callback URL needed
Storage	User's own private GitHub repo	Free, private, version-controlled
Sync engine	isomorphic-git (pure JS)	Works on iOS/Android — no native binaries
File system	Custom adapter wrapping DataAdapter	Obsidian's API works on all platforms
HTTP	Obsidian's `requestUrl` API	Bypasses CORS, works on mobile

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. Start watch mode (no .env / secret needed — Client ID is entered at runtime)
npm run dev

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

For bugs and feature requests, open an issue.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
buffer-shim.mjs		buffer-shim.mjs
esbuild.config.mjs		esbuild.config.mjs
manifest.json		manifest.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
versions.json		versions.json

Latest commit

History

Folders and files

Repository files navigation