Update README.md

README.md

@@ -2,19 +2,9 @@
 
 Plugin to sync a GitHub repository with an Obsidian vault.
 
-> [!CAUTION]
-> This is still in beta, logging is enabled by default.
-> I suggest you don't disable for the time being while using the plugin
-> as the logging information might be useful to fix some issues.
-
 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.
 
-### Issues
-
-If you find any problem please open an issue with as many details as possible.
-If could include the `github-sync.log` file found in your config directory that would be very helpful.
-
 ## Features
 
 These are the main features of the plugin:
@@ -24,13 +14,13 @@ These are the main features of the plugin:
 - Multiple vaults sync
 - Automatic sync on fixed interval
 - Manual sync
+- Conflict resolution view
 
-- 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.
+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](https://tfthacker.com/brat-quick-guide).
 
@@ -40,21 +30,36 @@ If you already have BRAT installed to install GitHub Sync copy the following lin
 obsidian://brat?plugin=https://github.com/silvanocerza/obsidian-github-sync
 ```
 
+### Issues
+
+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.
+
+![Enable logging](./assets/log_enable.png)
+
 ## Usage
 
 ### First sync
 
-When starting the plugin for the first time a dialog will guide you through the setup process.
+> [!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.
 
-If you already have files in your vault I strongly recommend you to create a new private GitHub repository and sync with that.
+You must also configure the plugin settings before syncing.
 
-> [!NOTE]
-> Onboarding is currently not supported on mobile.
+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.
 
 ### 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.
+The token must have the `Contents` permission set to `Read and write` like in the screenshot below.
 
 ![GitHub Fine-grained token](./assets/token_permissions.png)
 
@@ -71,12 +76,26 @@ If you don't want to see the button you can hide it, just check the plugin setti
 
 The `Sync with GitHub` command is also available.
 
+### Conflict resolution
+
+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.
+
+![Split conflict resolution](./assets/split_diff_view.png)
+![Unified conflict resolution](./assets/unified_diff_view.png)
+
+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.
+
 ### 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 that the `.obsidian` folder will always be present, that happens cause the plugin
+Note that the `.obsidian` folder will always be present, this happens because the plugin
 needs to store some metadata to correctly sync
 
 > [!CAUTION]
@@ -85,10 +104,23 @@ needs to store some metadata to correctly sync
 
 ### Reset
 
-I still have to add a reset button to clean the plugin settings and metadata.
+If you need to reset the plugin settings and metadata you can easily do that in the settings.
 
-For the time being you can reset the plugin by disabling it in the plugins list and deleting the `github-sync-metadata.json`
-and `github-sync.log` files in your config directory, `.obsidian` by default.
+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.
+
+## What's different from other sync plugins?
+
+There are obviously other plugins that let you sync your vault with GitHub or other git hosts, like [`obsidian-git`](https://github.com/Vinzent03/obsidian-git) and [`Obsidian-GitHub-Sync`](https://github.com/kevinmkchin/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`](https://isomorphic-git.org/).
+
+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.
 
 ## License