# Gitless Vault Sync

Sync your Obsidian vault with a GitHub repository, on desktop and mobile. No server, no Git on your device.

[Install in Obsidian](https://community.obsidian.md/plugins/github-vault-sync) · [Website](https://vaultsync.tushar.ai/) · [Guide](docs/guide.md)

[![The film's poster: a laptop's edit and a phone's edit landing in one note, under the word Both. Click to watch it.](https://raw.githubusercontent.com/triptu/markdown-github-sync/main/site/vaultsync/poster-v2.jpg)](https://vaultsync.tushar.ai/)

Your notes stay in a repository you own, with history you can browse on GitHub.

## What you get

![The plugin's settings in Obsidian, connected to a repository and showing the last sync time, automatic sync, Obsidian settings sync and history](https://raw.githubusercontent.com/triptu/markdown-github-sync/main/docs/images/settings.png)

**Sync runs on its own.** It runs after you pause typing and when you leave Obsidian.

![The conflict view for one note, with this device's paragraph in green and GitHub's in blue, and buttons to keep either, keep both, or edit and combine](https://raw.githubusercontent.com/triptu/markdown-github-sync/main/docs/images/conflict.png)

**Edits merge on their own.** Changes to different files, or to separate parts of a note, combine without asking. When they clash, you pick this device's version, GitHub's, both as two notes, or a combination you edit.

![File history for a note, listing its versions by device and time, with one version previewed and a Restore this version button](https://raw.githubusercontent.com/triptu/markdown-github-sync/main/docs/images/file-history.png)

**Every note keeps its history.** File history lists a note's past versions from all your devices. Preview one and restore it as a new change.

![The review step for settings arriving from another device, listing Appearance and Hotkeys with an Apply 2 updates button](https://raw.githubusercontent.com/triptu/markdown-github-sync/main/docs/images/settings-review.png)

**Themes, hotkeys and plugins sync too.** You review them before they change on another device.

[Notes for Android](https://notes.tushar.ai/) edits and syncs the same vault on an Android phone.

## Install

In Obsidian, go to Settings → Community plugins → Browse and search for Gitless Vault Sync, or open its [plugin page](https://community.obsidian.md/plugins/github-vault-sync). Create one repository on GitHub with "Add a README file" ticked. Then, on each device:

1. Turn off any other sync plugin, then enter the repository in this plugin's settings.
2. Click Create token. GitHub's token form opens with the permissions filled in (Contents read and write). Pick just that repository on the form, and paste the token back into settings.
3. Click Connect, look over what the first sync will do, and click Start syncing.

The [guide](docs/guide.md) covers what doesn't sync and troubleshooting.

## Privacy and network use

- The plugin connects only to GitHub: `api.github.com` (REST and GraphQL) for the repository, and `codeload.github.com` to download a commit's files in one go.
- `github.com` is only opened in your browser, when you click the link to create a token or to view a commit. The plugin makes no requests to it.
- Your token stays in Obsidian's secret storage on each device and is sent only to GitHub.
- It uploads your notes and the Obsidian settings that sync to the repository you choose. It reads only files inside the vault, and keeps its journal in `.git-vault-sync/` there.
- It uses base64 (`atob` and `btoa`) only because GitHub's API sends and receives file contents as base64. Nothing is hidden or obfuscated; the code is open source.
- It writes to the clipboard only when you tap **Copy link** next to the token field, and never reads it.
- No telemetry, analytics or ads. It's free and open source.