This article is brought to you by the team behind OB Lite — an app that reads and writes your GitHub-hosted vault straight from your phone. Struggling with mobile sync? Chapter 6 is your shortcut.
What obsidian-git actually does
obsidian-git is a free community plugin that treats your Obsidian vault (your notes folder) as a git repository, letting you record changes (commit), upload them (push) and fetch them (pull) from inside Obsidian. It can run all of this automatically on a schedule, so once configured, your notes back themselves up to GitHub while you just write.
You get three things: sync across multiple PCs, full version history for every note (you can always roll back), and automatic backup to GitHub. All without a subscription — which is why so many people choose git sync over the official Obsidian Sync.
To be honest about the trade-off: on desktop the plugin is stable and excellent, but on mobile Obsidian it faces hard technical limits, and a different strategy works better there. More on that at the end of the article.
Prerequisites: Git and a GitHub repository
The plugin does not work on its own. You need Git itself installed on your PC, and a GitHub repository to sync with.
Installing Git (Windows)
- Download the installer from git-scm.com and run it
- The installer shows about ten option screens — keeping every default and clicking "Next" is fineGit Credential Manager, which handles sign-in for you, is included.
- After installing, restart your PC (so the PATH change reliably takes effect)
Installing Git (Mac)
- Open Terminal and type
git --version - If a version number appears, you already have it. If macOS offers to install the "command line developer tools", accept
About the GitHub repository
Don't worry if you have no repository yet. Chapter 3, "Connecting your vault to GitHub", includes a plugin-only route (Route B) that creates one from scratch. Either way merges back into the steps below.
Installing and initial setup
Install the plugin
- Open Obsidian's Settings → Community plugins and turn off Restricted modeThe first time, Obsidian asks you to confirm enabling community plugins — go ahead.
- Click Browse and search for "Git", then install and enable obsidian-git (listed simply as "Git")
Register the name and email used for commits
git records "when and by whom" on every commit. If the "whom" part is missing, commits fail with an error — so you register it once, up front. This is the only step that touches a terminal, and it's just two lines to paste.
Open a terminal (Windows: press Start, type "cmd", open Command Prompt / Mac: search for "Terminal" in Launchpad). Paste the following two lines one at a time, replacing the name and email with your own, and press Enter after each.
git config --global user.name "Your Display Name" git config --global user.email "the-email-you-used-on-github"
The display name only appears in commit history — it does not need to match your GitHub username. If you'd rather not expose your email address, GitHub provides a private "…@users.noreply.github.com" address under Settings → Emails.
Connecting your vault to GitHub
This part splits into two routes, depending on where your vault stands today.
Route A | Your vault is already a repository (published with GitHub Desktop, etc.): nothing to do. The plugin detects it automatically — if the status bar at the bottom right shows git information, you're set. Skip ahead to "First authentication and checking it worked".
Route B | Your vault has never touched git: five steps, all within the plugin.
- In your browser, open github.com, click "+" at the top right → New repository. Name it (e.g. my-vault), make sure Private is selected, leave every checkbox like "Add a README file" unchecked, and press Create repositoryLeaving the checkboxes empty keeps the repository empty — a README created here would conflict with your first push.
- Copy the HTTPS URL shown on the next screen (https://github.com/yourname/my-vault.git)
- Back in Obsidian, open the command palette (Ctrl/Cmd+P) and run "Git: Initialize a new repo"
- Then run "Git: Edit remotes" — name the remote
originand paste the URL you copied in step 2 - Run "Git: Commit-and-sync". If it asks about branch names or upstream, accepting the defaults with Enter/OK is fine
First authentication and checking it worked
The first push asks you to sign in to GitHub. A browser window opens automatically — sign in and approve, and you're done. (That's Git Credential Manager, installed alongside Git; it won't ask again.)
Final check: open your repository on github.com. If your vault's notes and folders are listed there, initial setup is complete — from here on, the auto-sync settings in the next chapter take over.
Recommended auto-sync settings
In the plugin settings (Settings → Git), changing just three things gets you to "it syncs while I write".
- Auto commit-and-sync interval: 10 minutesToo short and your history becomes confetti; too long and devices drift apart. 10–15 minutes is a comfortable balance.
- Pull on startup: ONFetches other devices' changes the moment Obsidian opens. The single most effective conflict prevention.
- Put the date in commit messages (the {{date}} template)Makes it obvious which snapshot is which when you browse history later.
Setting names shift a little between plugin versions. If you can't find one, search the settings screen for "auto" or "pull".
Five common problems and their fixes
1. "Git is not installed" appears
Git itself is missing, or Obsidian can't see it on the PATH. Install from git-scm.com, restart your PC, and reopen Obsidian. If it's installed and the error persists, first check that git --version works in a terminal.
2. Authentication errors on push
Either the first-push sign-in never happened, or stored credentials have gone stale. With Git Credential Manager installed, pushing opens a browser window asking you to sign in to GitHub — do that and you're fixed. If you once authenticated with the old password method, delete the stale entry (on Windows: Credential Manager → remove the github.com items) and push again.
3. A merge conflict happened
Editing the same note on two devices before syncing causes a conflict. The note will contain two versions wrapped in <<<<<<< and >>>>>>> markers. Keep the content you want, delete the marker lines, save and commit — resolved.
Two prevention habits: pull before you start writing (keep Pull on startup ON), and don't leave devices unsynced for days (the classic failure is an old laptop pushing stale notes).
4. workspace.json shows up as changed every time
"I didn't write anything, why is there a diff?" — this is almost always the cause. .obsidian/workspace.json just records which notes are open right now, so it isn't worth syncing. Add this line to a .gitignore file in your vault root and it disappears from diffs: .obsidian/workspace.json
5. Unstable or slow on mobile
This one is not a configuration mistake — it's a structural limit. Mobile Obsidian can't run real git, so the plugin falls back to a JavaScript reimplementation. The plugin's own documentation calls mobile support experimental, and large vaults commonly hit out-of-memory crashes and extremely slow clones. For your phone, the setup in the next section is the realistic answer.
What to do about your phone
The short version: run obsidian-git on your desktop, and use a git-free way to read and write on your phone. Give up on running git on the phone itself, and mobile-side conflicts and crashes disappear together.
OB Lite covers the phone side
OB Lite is a PWA that reads and writes your GitHub-hosted vault straight from your phone's browser. Zero git setup on the phone. Each save becomes one commit, checked against the remote first — so it never fights your desktop obsidian-git. Reading and basic editing are free.
With this setup, your desktop keeps today's obsidian-git automation unchanged. Anything you write on the phone lands on the PC the moment Obsidian opens, via Pull on startup.