Quick Start
Up and running in minutes
For users already familiar with GitHub, PATs, and Obsidian's Community Plugins. Skip the hand-holding.
New to GitHub or unsure about any of these steps? Read the full guide for beginners — it covers everything from account creation.
Install the plugin
In Obsidian, open Settings → Community Plugins → Browse. Search for Direct GitHub Sync and install it. Enable it after installation.
Community Plugins must be enabled first. Go to Settings → Community Plugins and turn off Restricted Mode.
Create a GitHub repository
Create a new GitHub repository for your vault. It can be public or private. Leave it empty — the plugin will populate it on first push.
Generate a Personal Access Token
Go to GitHub → Settings → Developer Settings → Personal access tokens → Fine-grained tokens.
Required permissions on the repository:
- Contents — Read and write
- Metadata — Read-only
Your token must begin with ghp_ or github_pat_. The plugin validates this on save.
Configure the plugin
Open Settings → Direct GitHub Sync and fill in:
| Field | Value |
|---|---|
Personal Access Token |
Your PAT starting with ghp_ or github_pat_ |
GitHub Username |
Your GitHub handle |
Repository Name |
The repo name (not the full URL) |
Branch |
main (default) or your preferred branch |
Device Name |
Optional — useful for multi-device tracking |
Ignored Paths |
Comma-separated list of paths to exclude |
Concurrency |
5 (default, adjust if needed) |
Push your vault
Open the Command Palette (Ctrl/Cmd + P) and run Direct GitHub Sync: Push vault to GitHub. The status bar at the bottom will display sync progress.
Pull on another device
Repeat steps 1 and 4 on any other device, using the same repo details. Then run Direct GitHub Sync: Pull vault from GitHub to download your vault.
Settings reference
ignoreObsidianDir
When enabled (default), the .obsidian folder is excluded from sync. This is recommended if you use different themes or plugins per device.
ignoredPaths
Newline or comma-separated list of paths to exclude. Supports simple prefix matching. Example: Private/, Archive/old.
concurrency
Number of files uploaded simultaneously. Default is 5. Reduce if you encounter secondary rate-limit errors on large vaults.
deviceName
An optional label for this device. Useful when syncing across multiple machines — commit messages will include the device name so you can trace which machine made which change.
The plugin does not auto-resolve merge conflicts. If both a local and remote file have changed since last sync, the remote version will win on pull. Always push before switching devices.
Hitting an error or unexpected behaviour? Check the troubleshooting guide.