Git Vault Sync

One-click Git sync for Obsidian, with interactive conflict resolution, on desktop and mobile. Push and pull your whole vault to a Git remote (GitHub via HTTPS token) with a single button — and pick exactly what goes into each commit.

Git Vault Sync is a pure-JavaScript plugin, so it needs no system git and works on Android/iOS as well as desktop.

Two sync engines

There's a Sync engine setting (Auto / Git / GitHub API); Auto picks the right one per platform:

• Desktop → Git engine (isomorphic-git): full local history and true two-parent merges.
• Mobile → GitHub API engine (Git Data API): transfers files one blob at a time instead of a whole packfile, so it syncs large repos on a phone without running out of memory. Selective sync / commit preview are git-engine only.

Both push and pull to the same GitHub remote, so all your devices stay in sync.

Engine asymmetry: the config folder

Both engines honor your Excluded paths and the repo's .gitignore with the same glob semantics, so a path you exclude on the desktop is also excluded when syncing from mobile.

One deliberate difference: the GitHub API engine always skips the whole config folder (.obsidian/), regardless of your exclude patterns. The config folder is hundreds of small, frequently-changing files; pulling them one blob at a time hits GitHub rate limits and mobile memory, and most desktop plugins there are useless on a phone anyway. So the API engine syncs your notes, not your Obsidian settings. The git engine (desktop) can sync .obsidian/ if you don't exclude it. Either way, the plugin's own data.json (which holds your token) is always excluded by both engines.

Features

• One-click sync — stage all changes → commit → fetch → merge → push.
• Conflict resolution UI — when a merge conflicts, a dialog lists each file and lets you keep the local version, the remote version, or edit the merged result by hand.
• Commit preview / selective sync — review every change before syncing and uncheck files you don't want to commit yet. Deselected edits stay safely on disk and out of the commit, even across a merge.
• Status-bar indicator — shows pending change count, a spinner while syncing, ✓ when clean, and the last-sync time on hover. Click it for a menu.
• Auto-sync — optional sync on startup and/or on a timer.
• Excluded paths — glob patterns (e.g. .obsidian/workspace.json) that are never committed or counted. Patterns and the repo's .gitignore apply on both engines; note the API engine additionally always skips .obsidian/ (see Engine asymmetry).
• Saved credentials — remote, branch, and token are stored once.

Requirements

• A Git repository on GitHub (or any HTTPS Git host).
• A Personal Access Token (PAT). Prefer a fine-grained token scoped to the single repo, with Contents: Read and write and an expiration date.

Installation

From the community plugin store (recommended)

1. In Obsidian: Settings → Community plugins → Browse.
2. Search for Git Vault Sync, then Install and Enable.

Updates then arrive automatically through Obsidian.

Via BRAT (early/beta builds — auto-updates)

BRAT installs plugins straight from a GitHub repo and keeps them updated. Works on desktop and mobile.

1. Install BRAT from the community plugin store and enable it.
2. Run BRAT: Add a beta plugin for testing and paste this repo's URL.
3. BRAT downloads the latest release and enables Git Vault Sync.

Manual

1. Download main.js, manifest.json, and styles.css from the latest release (or build them — see Building from source).
2. Copy the three files into <your-vault>/.obsidian/plugins/git-vault-sync/. On mobile, copy them into the same folder inside the vault (see TESTING.md for per-platform tips).
3. In Obsidian: Settings → Community plugins, enable Git Vault Sync.

Configuration

Open Settings → Git Vault Sync and fill in:

Run Git Vault Sync: Test connection to remote from the command palette to verify the URL and token.

⚠️ Security: the token is stored in plaintext in .obsidian/plugins/git-vault-sync/data.json. If your vault itself is a Git repo, make sure that file is .gitignored so the token is never committed.

Usage

• Sync — click the circular-arrows ribbon icon, the status bar (→ Sync now), or run Sync vault with Git.
• Review & sync — click the checklist ribbon icon (or Review changes & sync) to open the commit preview, uncheck files, then Sync selected. This is git-engine only, so the icon is hidden under the API engine (the default on mobile).
• Resolve conflicts — if a merge conflicts, the resolution dialog opens automatically. Choose per file: Use local, Use remote, or Edit manually, then Resolve & sync. Cancel aborts the merge cleanly.
• Choose / create a branch — in Settings → Git Vault Sync the branch picker lists the remote's branches; pick Create new… to make one. The new branch is created on the remote (forked from the current branch), so the first sync to it doesn't fail with "branch not found".
• Initialize / link a repo — on a fresh vault, Settings → Git Vault Sync → Initialize runs git init, links the remote, fetches, and checks out the remote branch.

Building from source

npm install
npm run dev     # watch + rebuild
npm run build   # type-check + production bundle → main.js

For development, symlink the project into a test vault so rebuilds are picked up:

ln -s "$(pwd)" /path/to/Vault/.obsidian/plugins/git-vault-sync

Architecture

The whole vault is the working tree (<vault>/.git). All Git operations go through isomorphic-git over Obsidian's own filesystem and HTTP, so they work identically on desktop and mobile, with a GitHub Git Data API engine as the default on mobile. See src/ for the module layout (the filesystem/HTTP adapters, the two sync engines, and conflict handling) and CONTRIBUTING.md for the gotchas.

Security

• Your Personal Access Token is stored in plaintext in this plugin's .obsidian/plugins/git-vault-sync/data.json. Obsidian has no secure secret storage available to plugins, so the token sits on disk unencrypted, like other Git plugins for Obsidian.
• The token is sent only to your configured Git remote over HTTPS (as a Basic auth header), never to any third party. It is not logged and not written into commits.
• If your vault itself is tracked by Git, make sure .obsidian/plugins/git-vault-sync/data.json (or the whole plugin folder) is in your vault's .gitignore, or your token will be pushed to the remote.
• Use a fine-grained token scoped to the single repo with Contents: Read and write and an expiration date, so a leak has the smallest possible blast radius.

License

MIT — see LICENSE.