An Obsidian + Git workflow for solo developers

If you write code alone, your project knowledge is scattered in a predictable way: the code and its history live in git, and the reasons live in your head, a notes app, or nowhere. Putting your Obsidian vault under git doesn't solve that by itself, but it gets your notes into the same kind of history as your code: dated, diffable, and searchable with tools you already use.

This is the setup I'd recommend if you're starting from scratch.

Why git and not just a sync service

Obsidian Sync, iCloud, Dropbox and friends are good at one thing: making the same files show up on every device. Some keep version history too. What they don't give you:

• Messages. A sync service knows a file changed at 14:02. It doesn't know you changed it because the retry logic was rewritten.
• History you can query. git log -- notes/payments.md, git log -S "rate limit", git blame. Your notes get the same archaeology tools as your code.
• One place for code and docs, if you choose to keep them in the same repo.

You can use both. A common pattern is Obsidian Sync for moving files between devices and git on one desktop as backup and history. The plugin docs cover this: you can disable the plugin on other devices, and set the pull merge strategy to "Other sync service" so git doesn't fight Sync over your files. Test any combination on a copy of the vault first.

Step 1: Put the vault in a repo

cd ~/vaults/dev-notes
git init
git branch -M main

Now the one decision that matters: what to do with .obsidian/. That folder holds your settings, installed plugins and hotkeys, plus some files that change constantly (open panes, recent files). Ignoring the whole folder is common advice, but it means a fresh clone opens with no plugins and default settings. I'd ignore only the noisy parts:

# Obsidian: per-device UI state
.obsidian/workspace.json
.obsidian/workspace-mobile.json

# Trash and OS junk
.trash/
.DS_Store

Two exceptions worth checking. Some plugins store API keys or tokens in their data.json under .obsidian/plugins/; ignore those plugin folders if the repo could ever be seen by anyone else. And if a file you didn't expect shows up in every commit, it probably belongs in .gitignore (remember to git rm --cached it, since ignoring an already-committed file does nothing).

Step 2: Add a remote

A private repo on GitHub, GitLab, Codeberg, or a self-hosted Gitea all work. Private repos are free on GitHub's free plan.

git remote add origin [e-mail]:you/dev-notes.git
git add .
git commit -m "init: vault baseline"
git push -u origin main

Even solo, a remote is worth it: it's your off-machine backup, and it's how a second computer gets the vault.

One warning: don't put secrets in notes. It's easy to paste an API key into a debugging note. Once it's committed and pushed, it's in the history for good (rotating the key is the fix, not deleting the note).

Step 3: Install Obsidian Git

The community plugin Obsidian Git handles commits, pulls and pushes from inside Obsidian. After installing and enabling it:

• Auto commit-and-sync interval: 10-15 minutes is a reasonable start. This commits any changes, pulls, and pushes.
• Pull on startup: on. This is what saves you when you switch machines.
• Commit message: the default is vault backup: {{date}}. Fine for automatic commits.

The plugin also has a source control view (stage, diff, commit) and a history view, so you rarely need the terminal. Its mobile support is marked experimental in the README, so don't make your phone a critical part of this.

Step 4: Two kinds of commits

Auto-commits are your safety net. They're noisy by design, and that's fine: nobody reads vault backup: 2026-09-27 14:10.

The commits worth writing by hand are the ones that capture why. When you change a note because something real happened (a decision, an incident, a surprising bug), commit it yourself with a message:

docs(auth): record why sessions moved from JWT to Redis

Refresh-token rotation kept breaking on multiple tabs.
See decisions/2026-09-auth-sessions.md

A loose convention like docs(area): ... for notes and your usual style for code is enough. The payoff comes months later:

# Everything that ever touched the auth notes, with messages
git log --oneline -- notes/auth/

# When did "idempotency key" first appear anywhere in the vault?
git log -S "idempotency key" --oneline

Don't bother rewriting history to squash auto-commits. Force-pushing main to make the log look tidy is risky once a second machine is pulling from it, and git log --grep/-S/-- path already let you ignore the noise.

Same repo as the code, or separate?

Separate vault repo works best when your notes span several projects, which for most solo developers they do. It also keeps notes out of any repo you might later open-source.

A docs/ or notes/ folder inside the project repo works when the notes are strictly about that one codebase. The upside is that a code change and its explanation can land in the same commit or PR, and git log shows them interleaved. You can still open that folder as its own Obsidian vault.

If you go with the same repo, keep the commits separate even when they're close in time:

git commit -m "refactor(api): split router into modules" -- src/
git commit -m "docs(api): note why routers are split by domain" -- notes/

That keeps git log -- src/ clean for code review and git log -- notes/ readable as a record of decisions.

When things go wrong

• Merge conflicts. If you edit the same note on two machines between syncs, you'll get a normal git conflict with markers in the file. Resolve it like code. Pulling on startup and a short auto-sync interval make this rare.
• Huge repo. Images and PDFs add up. Put attachments in one folder and consider Git LFS or keeping large files out of the vault.
• Plugin stops syncing. Check the plugin's notices, then run git status in a terminal. Nine times out of ten it's an auth problem with the remote or a conflict that needs resolving.

What you end up with

A vault that's backed up off-machine without thinking about it, readable on any computer with a clone, and a history where the important changes have a sentence explaining them. It's not fancy. The value shows up the first time you need to know when and why you changed your mind about something, and git log just tells you.

P.S. If your vault also runs on Dataview, I put 10 ready-to-paste queries for a developer vault in one free note (pay what you want): https://subengel.gumroad.com/l/dzanl