How to sync your Obsidian vault to GitHub

Put your vault in a private GitHub repository and let the Git plugin push it every ten minutes. That is the whole setup: one repository, one plugin, four settings. It costs nothing, it keeps every version of every note, and it is what lets my website build itself from my notes.

GitHub, in one minute

GitHub keeps files online with their full history. You need three words:

• A repository is a folder that remembers every version of every file.
• A commit is a save point: "this is what the folder looked like at 9:14".
• Push sends your save points to GitHub. Pull gets the ones from your other devices.

Why not iCloud or Dropbox? Because services like Cloudflare can read a GitHub repository and do something every time it changes. For me that something is rebuilding my website.

Step 1: a private repository

On GitHub: New repository, give it a name (mine is lassewehlmann-obsidian), choose Private, and leave everything else empty. No README, no licence. An empty repository is easier to connect.

Private matters. Your vault has drafts, client notes and things you would never publish. Nobody but you can see a private repository.

Step 2: let your Mac talk to GitHub

The easiest way is GitHub's own command line tool. With Homebrew installed, open Terminal and run these two lines, one at a time:

brew install gh

gh auth login

Answer the questions: GitHub.com, HTTPS, and yes to "Authenticate Git with your GitHub credentials". It opens the browser, you log in, done. From now on git on this Mac can push without asking for a password.

Step 3: connect the vault folder

In Terminal, go to your vault and connect it. Change the folder and the address to yours:

cd ~/Obsidian/your-vault
git init -b main
git remote add origin https://github.com/your-name/your-vault.git
git add -A
git commit -m "Add my vault"
git push -u origin main

The git add -A and git commit lines matter. Without them git has nothing to send, and the push happily tells you "Everything up-to-date" while GitHub stays empty.

Before the first push, run git status and read the list. Everything on it goes to GitHub. Private repository or not, it is good to know what is in there.

Step 4: the plugin

In Obsidian: Settings → Community plugins → Browse, search for Git, install it and switch it on. It used to be called Obsidian Git.

Step 5: make it automatic

Out of the box, every timer is off. Nothing happens until you press a button. In Settings → Git:

Setting	Value	Why
Auto commit-and-sync interval	10 minutes	your notes go up while you write
Auto commit-and-sync after stopping file edits	on	it waits for a pause, not the middle of a sentence
Pull on startup	on	a device starts with the latest notes
Auto pull interval	10 minutes	changes from your other devices arrive on their own

The plugin's settings live in the vault too, so your other computers get them with the first pull.

Two more settings in Obsidian itself save you trouble later. Settings → Core plugins: switch Sync off if you do not use Obsidian Sync for this vault. And Settings → Files and links: set a default folder for new notes, so the top of your vault stays clean.

On a phone

It works on iPhone and Android, a bit slower.

1. On GitHub: Settings → Developer settings → Fine-grained tokens → Generate. Repository access: only your vault. Permission: Contents, read and write. Copy the token.
2. On the phone: a new, empty vault in Obsidian, then install Git.
3. In its settings, under Authentication: your GitHub username, and the token as password.
4. Command palette → Git: Clone an existing remote repo. Paste your repository's address, clone into the vault's root, restart Obsidian.

Use a separate token for your devices. If you ever lose the phone, you delete that one token and nothing else breaks.

When it does not work

Two things went wrong for me on day one, so they will probably go wrong for you too.

"accepts 0 arg(s), received 7". I pasted gh auth login together with a little # comment on the same line. The Mac's Terminal does not treat # as a comment there, so gh got seven extra words and refused. Run each command on its own line, without anything after it.

"Everything up-to-date", but GitHub is empty. I had connected the folder but never committed the notes. git add -A, then git commit -m "Add my vault", then push.

The plugin says it cannot push. On a Mac: run gh auth login again. On a phone: the token is missing, expired or only allowed to read.

Two devices changed the same note. The plugin merges and, if it cannot, marks the conflict in the note. Pull on startup and the ten-minute timer make this rare.

And one rule: one sync tool per vault. Git plus iCloud or Obsidian Sync on the same folder fight each other, and your notes lose.

Next: How to host a website on Cloudflare Pages for free, where the website lives. The whole story in one post: How this site works, and how I built it.