mirror of
https://github.com/silvanocerza/github-gitless-sync.git
synced 2026-07-22 05:41:36 +00:00
86 lines
2.8 KiB
Markdown
86 lines
2.8 KiB
Markdown
# Obsidian GitHub Sync
|
|
|
|
Plugin to sync a GitHub repository with an Obsidian vault.
|
|
|
|
> [!CAUTION]
|
|
> This is still in beta.
|
|
|
|
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.
|
|
|
|
## Features
|
|
|
|
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
|
|
|
|
- Conflicts handling (TODO 🔨)
|
|
- Filtering by file type (TODO 🔨)
|
|
|
|
## Installation
|
|
|
|
The plugin is still in beta so it's 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](https://tfthacker.com/brat-quick-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
|
|
```
|
|
|
|
## Usage
|
|
|
|
### First sync
|
|
|
|
When starting the plugin for the first time a dialog will guide you through the setup process.
|
|
|
|
If you already have files in your vault I strongly recommend you to create a new private GitHub repository and sync with that.
|
|
|
|
> [!NOTE]
|
|
> Onboarding is currently not supported on mobile.
|
|
|
|
### Token
|
|
|
|
A GitHub Fine-grained token is required to sync with your repository. You can create one by clicking [here](https://github.com/settings/personal-access-tokens/new).
|
|
The token must have the `Contents` permission set to `Read and write` like in the screenshow below.
|
|
|
|
|
|
|
|
I also suggest creating the token with access only to your sync repo.
|
|
|
|
### Sync modes
|
|
|
|
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.
|
|
|
|
### Config sync
|
|
|
|
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]
|
|
> The `.obsidian` folder will always be in the root of your repository, even if you choose
|
|
> to not sync vault configs. That happens cause the plugin needs to store some metadata to
|
|
> correctly sync.
|
|
|
|
### Reset
|
|
|
|
I still have to add a reset button to clean the plugin settings and metadata.
|
|
|
|
For the time being you can reset the plugin by disabling it in the plugins list and deleting the `github-sync-metadata.json`
|
|
file in your config directory, `.obsidian` by default.
|
|
|
|
## License
|
|
|
|
The project is licensed under the [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html) license.
|