- Create an empty private repository on GitHub.
- On your computer, add a
.gitignore, commit the vault folder and push it. - Install the Obsidian Git community plugin on the computer and turn on automatic commit-and-sync and pull on startup.
- On iPhone, iPad or Android, clone the repository into a folder Obsidian can open, then open it with Open folder as vault.
- Make one edit on each device and confirm it arrives on the other before you rely on it.
Jump to your device: Mac, Windows or Linux · iPhone and iPad · Android
Is Git the right sync method for you?
Git syncs snapshots that you commit, not every keystroke. Three trade-offs come with it:
- Sync is a step, not a background service. Obsidian’s own guide to syncing notes lists Git as an option for Windows, macOS and Linux, and notes that you push and pull by hand. The plugin can do this on a timer on your computer. Phones need a separate client.
- Conflicts are yours to resolve. If two devices change the same lines before either syncs, Git stops and asks you to choose.
- Private is not encrypted. A private GitHub repository limits who can open it, but GitHub can still read the files. Git doesn’t add end-to-end encryption.
If you’re still choosing, compare Obsidian Sync and Git or iCloud and Git. If you want history, your own repository and no subscription, read on.
What you need
- A GitHub account. A private repository is free.
- Obsidian on each device.
- Git on your computer, and the Obsidian Git community plugin (listed as Git, by Vinzent).
- For phones, a Git client: GitSync.md (iPhone, iPad and Android), or the Obsidian Git plugin itself, with the limits explained in Step 4.
- A separate backup of the vault before you change how it syncs.
Use one sync method per vault. Turn off iCloud, OneDrive, Dropbox, Google Drive, Syncthing or Obsidian Sync for this vault, and keep the vault in a normal local folder that none of them manage. Two tools rewriting the same files cause duplicate notes and confusing conflicts.
Step 1: Create a private GitHub repository
- On GitHub, select New repository.
- Give it a name, such as
notes, and choose Private. - Leave the README,
.gitignoreand license options off. Your vault will be the first commit, and an empty repository avoids a merge on the first push. - Create it, and copy the HTTPS URL, which looks like
https://github.com/YOUR_ACCOUNT/notes.git.
GitHub documents this in Creating a new repository and Adding locally hosted code to GitHub.
Step 2: Put your vault under Git on your computer
Install Git
- macOS: run
xcode-select --installin Terminal to get Apple’s Command Line Tools, which include Git, or install Git with Homebrew. See Git for macOS. - Windows: install Git for Windows with its default options, which include Git Bash and Git Credential Manager. The plugin’s installation notes say GitHub Desktop alone isn’t enough and ask for Git 2.29 or later.
- Linux: install Git from your distribution’s package manager, for example
sudo apt install git. See Git for Linux. The plugin’s notes say Obsidian installed as a Snap can’t reach Git, and Flatpak isn’t recommended. The AppImage works.
Windows has a few extra details, such as OneDrive-redirected Documents folders. If that’s you, follow the Windows and iPhone walkthrough, which runs the same steps in Git Bash.
Start the repository
These examples use a vault at ~/Notes. Replace the path, name and email with your own. Run git status first: if it says the folder is already a repository, skip git init.
cd ~/Notes
git init -b main
git config user.name "Your Name"
git config user.email "you@example.com"
The email is published in every commit. GitHub’s no-reply address works if you’d rather keep yours private. git init -b needs Git 2.28 or later.
Add a .gitignore before the first commit
Create a file named .gitignore in the vault folder, next to .obsidian. This starter shares notes, attachments and most settings, and keeps per-device files local:
# Window layouts change on every device
.obsidian/workspace*.json
# Deleted notes and operating-system files
.trash/
.DS_Store
Thumbs.db
Obsidian rewrites workspace.json and workspace-mobile.json whenever you open a note, so tracking them creates a change on every session. Ignore rules only affect files Git isn’t tracking yet, which is why the file goes in before the first commit. If you’d rather keep all settings and plugins per device, ignore .obsidian/ instead. The Obsidian .gitignore guide compares both choices, and Git’s gitignore documentation explains the pattern rules.
Commit and push
git add .
git status
git diff --cached --stat
git commit -m "Add vault notes"
git remote add origin https://github.com/YOUR_ACCOUNT/notes.git
git push -u origin main
Before you commit, read the git status list. Make sure no private documents, tokens or very large files are about to be uploaded. When the push finishes, open the repository on GitHub and check that your notes are there.
Sign in on the desktop
GitHub doesn’t accept your account password for Git over HTTPS. Use one of these:
- HTTPS with a credential helper. On Windows, Git Credential Manager opens a browser sign-in on the first push. On macOS, the plugin’s authentication page suggests
git config --global credential.helper osxkeychain, and on Linux,libsecret. After one successful push from the terminal, the plugin can pull and push without asking. - SSH. Create a key, add it to
ssh-agentand to GitHub, as described in GitHub’s SSH documentation, and use thegit@github.com:remote URL.
If you use a personal access token, enter it only when Git or an app asks for it. Never paste a token into a note: it would be committed and pushed with the vault.
Step 3: Install and configure the Obsidian Git plugin (desktop)
In Obsidian, open Settings → Community plugins, turn on community plugins if Obsidian asks, then select Browse. Search for Git, choose the plugin by Vinzent, then Install and Enable. Obsidian’s community plugins help covers this screen. The plugin finds the repository in the vault folder on its own.
Then open the plugin’s settings, under Community plugins → Git. Most defaults are sensible, but automatic sync is off until you set an interval. These are the settings worth changing, with the names used in release 2.43.0:
| Setting | Recommended | Why |
|---|---|---|
| Auto commit-and-sync interval (minutes) | 10 | The default is 0, which means off. With an interval, the plugin commits, pulls and pushes on a schedule while Obsidian is open. |
| Auto commit-and-sync after stopping file edits | On | Waits until you stop typing, so a commit doesn’t land in the middle of a sentence. |
| Pull on startup | On | Off by default. Turning it on brings in your phone’s edits as soon as you open Obsidian on the computer. |
| Auto pull interval (minutes) | 10 | Pulls on its own timer, separate from committing. Useful when the computer stays open while you write on the phone. |
| Use separate commit and push intervals | Off | Keeps commit and push together. Turn it on only if you want frequent local commits and less frequent pushes, then set Auto push interval (minutes). |
| Push on commit-and-sync | On (default) | Turning it off makes commit-and-sync a local commit only, and your phone never sees the change. |
| Pull on commit-and-sync | On (default) | Pulls before pushing, so the push isn’t rejected when the phone pushed first. |
| Merge strategy | Merge (default) | The simplest choice. Rebase rewrites your local commits, and the plugin doesn’t support it on mobile. |
| Commit message on auto commit-and-sync | vault backup: {{date}} ({{hostname}}) | The default is vault backup: {{date}}. Adding {{hostname}} shows which device made each commit. Set a short name in {{hostname}} placeholder replacement, such as laptop. |
To sync by hand, open the command palette and run Git: Commit-and-sync or Git: Pull. The Open source control view command shows changed files and diffs.
Step 4: Add your phone
This is where most Git vault setups break. On iPhone, iPad and Android, Obsidian plugins can’t run a native Git program. The Obsidian Git plugin uses isomorphic-git, a JavaScript implementation of Git, instead. Its README marks mobile support as experimental and “highly unstable”, and lists these limits:
- no SSH authentication
- limited repository size, because of memory limits
- no rebase merge strategy
- no submodules
It also warns that Obsidian may crash on clone or pull, depending on the device and free memory. The plugin is still the right tool on desktop. On a phone, it can be enough for a small vault with an HTTPS remote. For anything larger, or for SSH, use a native Git client that writes into the folder Obsidian opens.
GitSync.md is one such client. It is a different app from the open-source app called “GitSync” that the plugin’s README mentions. The two aren’t related.
iPhone and iPad
On iOS, the vault has to be a local folder both apps can reach, usually On My iPhone → Obsidian (or On My iPad → Obsidian). The Git route here doesn’t use an iCloud Drive vault folder, so leave Store in iCloud off when you create the vault. You have two routes:
- Obsidian Git on the phone. Clone the vault into Obsidian’s local folder, then install the plugin in that vault and give it a GitHub personal access token. Set up an Obsidian Git token on iPhone walks through it. The mobile limits above apply.
- A native Git client. In GitSync.md, sign in with GitHub or paste a personal access token, set the save location to On My iPhone → Obsidian, and clone the vault repository. Then open that folder in Obsidian with Open folder as vault. GitSync.md uses libgit2 to pull, commit and push, over HTTPS or SSH, and stores credentials in the iOS Keychain. The iPhone and iPad guide has the full setup.
You can also mix them: let GitSync.md clone the vault, and let the plugin do daily syncing inside Obsidian. For GitHub HTTPS vaults signed in with GitSync.md’s GitHub account, the free GitSync.md Connect plugin hands your sign-in to Obsidian Git, so you don’t copy a token between apps. Connect needs GitSync.md 2.8.0 or later, and it doesn’t change the plugin’s mobile limits.
GitSync.md needs iOS 17 or iPadOS 17 or later. It costs $9.99 once on the US App Store; local prices may vary.
Get GitSync.md for iPhone and iPad →
Android
On Android, the vault must be in a device folder that both Obsidian and the Git client can open, such as Documents/Obsidian/Notes. Cloud folders like Google Drive can’t hold a Git working copy. You have three routes:
- Obsidian Git plugin: everything inside Obsidian, with the mobile limits above. Fine for a small vault over HTTPS.
- Termux and a script: real command-line Git, but you maintain the packages, keys, scripts and any scheduling yourself.
- A native Git client: GitSync.md clones into a device folder you choose, shows diffs and conflicts, and supports GitHub sign-in, tokens and SSH keys. It needs Android 9 or later and all-files access to manage Git folders outside its own storage.
The Android guide compares the three routes and walks through storage access, the clone location and Background Sync. GitSync.md costs $9.99 once on Google Play, after a free vault check; local prices may vary.
Get GitSync.md on Google Play →
If your .gitignore shares .obsidian/, the Obsidian Git plugin and its timers also arrive on the phone. If GitSync.md handles Git on the phone, open the plugin’s settings there and turn on Disable on this device under Advanced. It applies to that device only, so the plugin keeps running on your computer. Two Git clients working on the same folder at once make errors hard to trace.
Step 5: Verify sync in both directions
- On the computer, create
sync-test.mdwith one line of text. Run Git: Commit-and-sync, or wait for the interval. - Open the repository on GitHub and check that the commit and the file are there.
- On the phone, pull: in GitSync.md, open the vault and pull, or run Git: Pull in Obsidian if you use the plugin. Open
sync-test.mdin Obsidian. - Edit the note on the phone. Commit and push it.
- Check GitHub for the new commit, then pull on the computer (or restart Obsidian with Pull on startup on) and confirm the phone’s edit is there.
Only rely on automatic sync after both directions work. If you have a tablet or a second computer, repeat the test there.
Daily routine and avoiding conflicts
- Pull before you edit, push when you finish. On the computer the plugin does this with Pull on startup and its interval. On a phone, pull when you open the vault and push before you put the phone down.
- Don’t edit the same note on two devices while one is offline. Writing offline is fine, but the first device to push wins, and the second gets a conflict on any lines both changed.
- Resolve conflicts, don’t force-push. Keep one version, or combine both by hand, then commit. The conflict recovery guide explains the options.
Automatic sync on a phone is limited by the operating system. GitSync.md has optional Background Sync on iPhone, iPad and Android, but iOS and Android decide when it runs, so it is never real time. On iPhone, read what background Git sync can do. Open the app before you switch devices if you need the latest notes.
Troubleshooting
Authentication failed
On desktop, push once from the terminal so the credential helper or SSH key is set up, then retry in Obsidian. GitHub rejects account passwords for Git: use a credential manager, SSH or a token. On a phone, check that the token or account has access to the repository, and that it hasn’t expired.
“not a git repository”
The vault Obsidian opened isn’t the folder that contains .git. Often a parent folder or a nested copy was opened. Open the repository root as the vault, the folder that holds both .git and .obsidian.
The plugin doesn’t work on the phone
Check the README’s mobile limits first: SSH remotes don’t work, and large vaults can crash on clone or pull. Switch to an HTTPS remote with a token, or use a native Git client. For iPhone symptoms, see Obsidian Git not working on iPhone.
A commit every time you open Obsidian
A workspace file is still tracked. Add it to .gitignore, then stop tracking it once with git rm --cached .obsidian/workspace.json and commit. See the .gitignore guide.
Large images, audio or PDFs
Git keeps every version of every file, so big attachments make the repository slow to clone, especially on phones. Git LFS stores large files outside history, but every client you use has to support it. See Git LFS on iPhone and iPad for how GitSync.md handles it.
FAQ
Is it free?
Git, the Obsidian Git plugin and a private GitHub repository are free. On phones, the plugin is free too. GitSync.md is a one-time $9.99 purchase on iPhone and iPad, and on Android, with no subscription. Local store prices may vary.
Is my vault private?
A private repository is visible only to you and the people you invite. It isn’t end-to-end encrypted: GitHub stores the files in a form it can read, and HTTPS or SSH only protects them in transit. See Obsidian Sync vs Git if you need encryption.
Does the Obsidian Git plugin work on mobile?
Yes, with limits. On iPhone, iPad and Android it uses a JavaScript Git implementation without SSH, and its README calls mobile support experimental and warns about crashes on larger vaults. For small HTTPS vaults it can be enough.
Can I use GitLab or a self-hosted server?
Yes. Git works with any remote: use its URL in git remote add. On iPhone and iPad, GitSync.md accepts manually entered remotes over HTTPS or SSH. See self-hosted Git with SSH on iPhone. On Android, use Any Git host.
Will plugins and themes sync?
Only if .obsidian/ is tracked. With the starter .gitignore above, themes, snippets, plugins and their settings sync, while window layouts stay on each device. If you ignore .obsidian/, configure each device separately. Review plugin settings before committing them, because some plugins store private data.
