Sync your files across mobile and desktop devices with one click.

Community project

This project is a community collaboration. If you'd like to contribute please check out the Discussions section on GitHub to suggest or discuss ideas.

Features

• Universally supported: sync your vault across multiple devices, supports both mobile and desktop
• Auto sync is now available 🎉
• One-click to sync your vault
• Conflict resolution: Stores conflicting changes from remote in the local _fit folder so you can resolve conflicts after sync
• Guided setup: Intuitive settings, easy to configure even if you are new to GitHub
• Works with existing vaults or repos

Note: This plugin is still in beta, please backup your vault before using this plugin.

Quick demo

Setup

1. Create a personal access token with read/write access to the repo for your vault (refer to Github: creating a personal access token). For fine-grained tokens, the only required permission is Contents: Read and Write under Repository permissions. For classic tokens, the repo scope covers this (though it grants broader access than strictly needed).
2. Once the personal access token is filled in, you can authenticate the user. The GitHub username, list of repositories, and branches will auto-populate.
3. Select a repo and branch and you are ready to sync.

NOTE: For security, it's recommended to limit the token scope to only the necessary repository for your vault and avoid sharing your entire plugin settings file that contains this token.

How Sync Works

What gets synced

✅ Synced files:

• Regular markdown files (.md)
• Attachments (images, PDFs, etc.)
• Any files in your vault root

❌ NOT synced (protected paths):

• .obsidian/ folder (Obsidian settings and plugins)
• _fit/ folder (conflict resolution area)
• Hidden files like .gitignore, .env (not currently supported - see #92 for planned opt-in support)

Conflict handling

When the same file is modified both locally and remotely, FIT:

• Keeps your local version in place
• Saves the remote version to _fit/path/to/file.md
• You can manually compare and merge the versions
• If the same file clashes again before you resolve it, the _fit/ version is overwritten with the latest remote version (sync doesn't fail)

See Common Issues below for detailed conflict resolution steps.

First sync

• It is advised to use a new repo for syncing an existing vault, to minimize the chance of file name conflict on the first sync
• If your existing vault or repo is large, the initial sync would take longer and require a good internet connection

Manually trigger sync on Obsidian mobile

related issue: #190

On Obsidian mobile, linking sync to a hotkey which requires the presence of a keyboard is not an ideal approach to manually trigger sync. A more intuitive set of procedures are:

• Open any repository with FIT configured
• Swipe down from anywhere on the screen to open command menu
• Search for "Fit: Fit Sync" and click to sync

Alternative: "Fit Sync" can be pinned to the ribbon menu from "Setting > Appearance > Interface > Ribbon menu configuration"

🔒 Security

The FIT maintainers make every effort to protect your security and protect against data loss. However, mistakes can happen. Users are highly recommended to do a security review of the code of this project before trusting it with their data. You could use an AI tool for that such as Claude Code.

You should also take care with security tokens you use to ensure they don't leak, because anyone with access to those can read and write your vault repository even if it's private (or worse if you configure broad unrestricted permissions on your token). In particular, avoid syncing your .obsidian/ files with other tools if you don't know what you're doing, and consider adding .gitignore rules to ignore .obsidian/ paths if you'll be syncing anything using git (FIT itself never syncs .obsidian/ - see How Sync Works).

Common Issues

Roadmap

See CONTRIBUTING.md for current milestone and long-term priorities.

Relevant plugins

There are other community plugins with more advanced git features, if you need features such as branching of your repo, Git is a nice plugin to check out.

There are also other plugins for synchronizing changes such as Git integration, GitHub sync, and YAOS. However, they do not support mobile yet as of writing this plugin.

Developer Documentation

For developers interested in contributing to FIT or understanding its architecture, comprehensive documentation is available in the docs/ directory in GitHub.

Acknowledgements

• This plugin used Obsidian Sample Plugin as a template.
• This plugin uses Octokit to interface with GitHub rest api across devices.