Git Sync
Sync your notes to a Git repository with GitHub integration.
Overview
mdnb can sync any vault to a Git repository. Sync is always manual: press the sync button when you want to commit and push your changes.
Setting Up
Open Settings > Git to configure sync. The vault list at the top shows all your vaults with their current git status. Click a vault to configure it.
Sign In to GitHub
Click Sign In with GitHub to authenticate via the GitHub device flow. You can also paste a Personal Access Token if you prefer.
Connect a Vault
Once signed in, you have three options:
- Connect to GitHub Repository: browse your existing repos and link one to the current vault
- Clone Existing Repository: clone a repo into a new folder (if you have local notes, mdnb offers to copy them into the clone)
- Create New Repository: run
git initon the vault to start tracking changes locally
Syncing
The sync button appears in the bottom-left of the sidebar when the active vault has a repository with a remote. Click it to sync.
A sync operation does the following:
- Stages all changes (
git add) - Commits with a timestamped message
- Pulls from the remote (
git pull) - Pushes to the remote (
git push)
An orange dot on the sync button indicates uncommitted changes or unpushed/unpulled commits.
You can also sync from Settings > Git using the "Sync Now" button, which shows more detail about the current status (uncommitted file count, ahead/behind counts, last sync time).
Status Indicators
Each vault in the Git settings shows a status badge:
| Badge | Meaning |
|---|---|
| No repo | No git repository in this vault |
| Local repo | Git initialized but no remote configured |
| Connected | Synced with remote, up to date |
| Pull needed | Remote has new commits |
| Push needed | Local commits not yet pushed |
Conflict Handling
If a merge conflict or rebase is detected, mdnb blocks sync and shows a message. Resolve conflicts in your preferred Git tool, then retry.
Gitignore
mdnb automatically maintains a .gitignore in synced vaults to exclude internal files (.DS_Store, *.automerge, .doc-manifest.json).
Disconnecting
To stop syncing a vault, open Settings > Git, select the vault, and click "Disconnect" at the bottom of the sync section. This removes the remote association but does not delete the local repository or your files.