Plugin to sync a GitHub repository with an Obsidian vault.
I highly recommend not using this plugin with another sync service. This might create problems for this plugin when determining what needs to be synced between remote repository and local vault.
These are the main features of the plugin:
-
Desktop and mobile support
-
Doesn't require
git -
Multiple vaults sync
-
Automatic sync on fixed interval
-
Manual sync
-
Conflict resolution view
-
Filtering by file type (TODO 🔨)
The plugin is still not available in the community plugins.
For the time being you can install it with BRAT. If you never used BRAT see the official quick start guide.
If you already have BRAT installed to install GitHub Sync copy the following link and paste it in the browser address bar.
obsidian://brat?plugin=https://github.com/silvanocerza/obsidian-github-sync
If you find any problem please open an issue with as many details as possible.
Please also provide logs if possible, you can find the github-sync.log file in your config directory. Remember to enable logging first.
Important
The first sync will only work if either the remote repository or the local vault are completely EMPTY. If both contain files the first sync will fail.
You must also configure the plugin settings before syncing.
These settings are mandatory:
- Your GitHub Token (see below)
- Repository owner
- Repository name
- Repository branch
If any of this is not set sync won't start.
A GitHub Fine-grained token is required to sync with your repository. You can create one by clicking here.
The token must have the Contents permission set to Read and write like in the screenshot below.
I also suggest creating the token with access only to your sync repo.
You can always sync manually by clicking the sync button in the side ribbon. This will always work even if sync on interval is enabled.
If you don't want to see the button you can hide it, just check the plugin settings.
The Sync with GitHub command is also available.
When you sync multiple vaults using this plugin you might risk creating conflicts between the remote and a local vault. This usually happens when the remote has a new update from vault A, but vault B edits the file before syncing with remote. That creates a conflict, by default we'll open a view to let you resolve the conflict since you should have all the necessary information to correctly resolve it.
By default the split view will be used on desktop and the unified one on mobile, you can change the settings to always use the one you prefer.
If you don't want to resolve them you can change the settings to always prefer either the remote or local version in case of conflicts.
If you want to sync your vault configs with other vault you can enable that.
It will sync the whole folder, that is .obsidian by default, including all plugins and themes.
Note that the .obsidian folder will always be present, this happens because the plugin
needs to store some metadata to correctly sync
Caution
DO NOT sync configs if your remote repository is public. That will expose the token you used to sync.
If you need to reset the plugin settings and metadata you can easily do that in the settings.
That will completely wipe all the sync metadata so you'll have to repeat the first sync as if you just enabled the plugin for the first time.
There are obviously other plugins that let you sync your vault with GitHub or other git hosts, like obsidian-git and Obsidian-GitHub-Sync just to name a couple.
Most of those plugins though require the git executable to be present in your system, they might rely on Bash scripts too. This makes them much less portable, it's harder to use on Windows, and mobile is really unstable because most of the times they rely on isomorphic-git.
This annoyed me because I wanted to have the same experience on every platform, and I wanted especially to support mobile.
So I went a different way and chose to sync only with GitHub using their REST APIs, this means I don't rely in anyway on git being present in your system. This way I can easily support desktop and mobile with the same identical logic, and some small necessary differences in the UI for a better user experience.
This obviously comes with some limitations. Since git is not used you can't interact with your repository locally in any way, and any git feature like branching, merging, or rebasing, are not available at all.
Also since this relies only on the GitHub APIs you can only sync with GitHub and no other host.
The project is licensed under the AGPLv3 license.