Short answer: choose a preset, adjust the boxes, then copy the file into the root of your vault’s repository. Every line is commented with why it is there. When some of the config folder syncs and some doesn’t, the file uses .obsidian/* followed by ! rules, which is the form Git honours. For a longer explanation, see the Obsidian .gitignore guide.

Build your .gitignore

Check it before you push

Save the file in the vault’s repository root, then ask Git which rule matches a path. It prints the file, line and pattern, or nothing if no rule matches:

git check-ignore -v .obsidian/workspace.json

Run it for one file you expect to be ignored and one you expect to sync (use -v --no-index if the file is already tracked). If a result surprises you, see when .gitignore seems not to work. Command reference: git check-ignore.

A .gitignore does not untrack files that are already committed. If workspace.json is already in your repository, remove it from the index once with git rm --cached .obsidian/workspace.json and commit. Steps are in the guide’s tracked-files section.

Which preset should I pick?

Notes only is the safest default. Your Markdown and attachments sync; the whole config folder stays on each device, so nothing private can leak through a plugin and there is nothing to merge. You set up themes and plugins again on each device. Details: the notes-only policy.

Notes + shared settings adds the things you want identical everywhere: themes, snippets, hotkeys and the plugins themselves. Window layout and plugin settings stay local. This is the preset most people with a desktop and a phone want. See sharing selected settings.

Everything except device state also syncs plugin settings, so a fresh clone is configured. Use it only for a private repository you have audited, because those files can contain tokens.

Why .obsidian/ plus ! doesn’t work

A common tip is to ignore the config folder and then re-include a piece of it:

# Does NOT work: snippets/ stays ignored
.obsidian/
!.obsidian/snippets/

Git’s documentation says: “It is not possible to re-include a file if a parent directory of that file is excluded. Git doesn’t list excluded directories for performance reasons, so any patterns on contained files have no effect, no matter where they are defined.” Once .obsidian/ is ignored, Git never looks inside it, so the ! line is silently dead. The fix is to ignore the folder’s contents instead, which leaves the folder itself visible to Git:

# Works: the folder is traversed, snippets/ is re-included
.obsidian/*
!.obsidian/snippets/

The generator writes this form whenever you mix ignored and synced items under the config folder, and never emits a parent ignore followed by a child negation. Source: gitignore pattern format in the Git documentation.

Plugin data can hold secrets

A plugin’s data.json is whatever that plugin chooses to save, and some plugins save API keys, access tokens or sync credentials there. The generator ignores these files unless you tick the box. If a token was already committed, ignoring the file is not enough: the token stays in history, so revoke or rotate it first, then follow the guide’s steps for previously committed secrets.

Use it on iPhone and iPad

On iPhone and iPad, GitSync.md stages changes with libgit2’s add-all, which leaves out files your repository’s .gitignore matches. The file travels with the repository, so the policy you generate here applies once you pull it. Like any Git client it does not untrack files that are already committed, so run the git rm --cached step on your computer first. Setup walkthroughs: Obsidian Git on iPhone and iPad; if sync misbehaves, Obsidian Git not working on iPhone.

Same .gitignore, every device

GitSync.md syncs your vault with real Git on iPhone, iPad and Android. Free to download, $9.99 once to unlock on iPhone and iPad.

Download on the App Store · Get it on Google Play

Frequently asked questions

Should I commit .obsidian at all?

Only if you want the same themes, snippets, hotkeys or plugins on every device. Ignoring the whole folder is the simplest policy, and you configure each device yourself. Sharing selected files keeps your setup consistent, but never share workspace.json, and review plugin data.json files for tokens before you commit them.

Will plugins work on a fresh clone if I ignore plugins/?

No. A fresh clone only has the files Git tracks, so ignored plugin code is not there and each plugin has to be installed again on that device. To bring plugins along, sync plugin code and keep the plugin settings (data.json) ignored unless you have checked them for secrets.

Does Obsidian Sync use .gitignore?

No. Obsidian Sync is separate from Git and has its own selective sync settings that choose which vault settings and file types to sync; see Obsidian’s Sync settings and selective sync. A .gitignore only affects Git. If you use both on one vault, keep them from fighting over the same files, or use one sync method per vault.

My config folder isn’t called .obsidian. Does this work?

Yes. Obsidian lets you rename the configuration folder (Obsidian Help: configuration folder), so the generator has a field for its name and writes every rule with that name. Type the exact folder name and check the result with git check-ignore.

The generator makes no network requests and saves nothing: what you type stays in this page.