Sync your files across mobile and desktop devices with one click.
- 添加了 forgejo remote 的支持, 可以添加除了 github 之外的远程仓库.
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.
- 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.
Sync status overview — an upcoming command ("Explain Sync Status") will open a detailed view of your vault's sync state: pending local changes, unresolved conflicts, files too large to push, and auto-sync timing. Preview:
- 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
reposcope covers this (though it grants broader access than strictly needed). - Once the personal access token is filled in, you can authenticate the user. The GitHub username, list of repositories, and branches will auto-populate.
- 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.
Beta builds can select Forgejo/Gitea as the remote provider. Configure a base URL such as https://git.example.com, an API token with repository contents read/write access, then enter owner, repo, and branch manually or use provider suggestions when available. GitHub remains the default provider.
✅ Synced files:
- Regular markdown files (.md)
- Attachments (images, PDFs, etc.)
- Any files in your vault root
❌ NOT synced (protected paths):
.obsidian/folder — excluded to prevent overwriting device-specific settings (selective opt-in coming in 1.6)_fit/folder (conflict resolution area)
Coming in the 1.6 release:
- Hidden files (
.gitignore,.env, etc.) will sync by default..gitignorerules are already respected — files matched by your patterns are excluded from sync.- Selective
.obsidian/sync — opt individual config files (appearance, hotkeys, graph settings, plugin data) in via Settings. Workspace layout files and plugin installer files are always excluded regardless.
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.
- 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
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"
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).
📁 Empty directories not syncing
Why: Git (and GitHub) doesn't track empty directories. This is a fundamental limitation of Git, not a FIT bug.
Solution: Add a placeholder file like _gitkeep or README.md to keep the folder. Empty folders will only sync once they contain files.
📦 File size limits - "input too large" errors
Why: GitHub API has file size limits (~100MB hard limit, issues with files >10MB).
Symptoms: Error messages like "input too large to process" or "File 'X' is too large..."
Solutions:
- Move large files (>20MB) outside your vault before syncing
- Manually sync large files to GitHub using other tools (to create them and any time they're modified)
- Add the files to
.gitignoreto exclude them from sync
⚠️ Sync conflicts - files in `_fit/` folder
What happens: When the same file is modified locally AND on GitHub, FIT saves both versions:
- Your local version stays in place
- The remote version is saved to
_fit/path/to/file.md
How to resolve:
- Find conflict files in the
_fit/folder - Compare both versions
- Manually merge the changes you want to keep
- Delete the
_fit/version when done - Sync again
Prevention: Sync regularly (enable auto-sync) and avoid editing the same file on multiple devices simultaneously.
🖼️ Images/PDFs showing as corrupted text in GitHub
Symptoms: Binary files (JPG, PNG, PDF) appear as gibberish text in GitHub like ����JFIF��... instead of displaying properly
Cause: Bug in v1.4.0-beta.3 where binary files were incorrectly read as text on some platforms
Solution:
- Check file history in GitHub to find bad changes
- Use git to restore previous versions OR manually copy from history
- Update to v1.4 stable when available or a different beta version
- Re-sync - files will upload correctly
Note: This only affected beta versions. Images and PDFs sync correctly in v1.4+.
More info: See joshuakto#156 about the regression and older "correct format" error.
See CONTRIBUTING.md for current milestone and long-term priorities.
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.
For developers interested in contributing to FIT or understanding its architecture, comprehensive documentation is available in the docs/ directory in GitHub.
- This plugin used Obsidian Sample Plugin as a template.
- This plugin uses Octokit to interface with GitHub rest api across devices.