The Obsidian Git plugin's own documentation calls its mobile implementation very unstable and recommends against using it at all. Most people read that as routine caution, the standard "works on my machine" disclaimer developers slap on things. But in practice mobile runs on an entirely different JavaScript git reimplementation, one that chokes on large vaults, resolves conflicts in the wrong direction without telling you, or just hangs mid commit with no consistent size threshold to point to. The sync appears to succeed. Your notes diverge underneath you anyway. This post is about why that happens and what setup actually holds up once you're on a phone.
Here's where I land after running this for a while: the Git plugin is genuinely good at version history and genuinely bad at cross device sync on mobile. People get burned when they ask it to do both at once.
Why Mobile Git Runs On Borrowed Engineering
Why Mobile Git Sync Fails: The Chain of Events
Step 1: No native binary allowed on iOS/Android
Step 2: Plugin ships JS reimplementation (isomorphic git) instead of real git binary
Step 3: Large vault (4000+ files) is walked in JS memory, no native fs shortcuts
Step 4: Commit hangs or conflict resolves silently in wrong direction
Step 5: Sync appears successful, notes diverge undetected
Source: Based on article analysis of Obsidian Git plugin mobile behavior
Desktop Obsidian Git shells out to a real git binary, the same one your terminal calls, hardened over two decades of merge conflicts, partial commits, weird line endings, huge binary blobs. It's boring in the best possible way. It just does what git has always done.
Mobile can't do that. iOS and Android don't let apps spawn native binaries the way desktop operating systems do, so the plugin ships its own git reimplementation written in JavaScript, commonly built on isomorphic git. That means translating the entire object model and pack file format into a language that was never built for the job. A clever implementation isn't an equivalent one, and that gap is exactly where the instability lives. Mobile isn't lagging a little behind desktop, it's running on a different engine entirely, and that engine chokes on the exact vault sizes most people who'd bother installing a plugin like this actually have. A few dozen markdown files and a folder of small images? You might skate by for months. Years of daily notes, embedded PDFs, a plugin ecosystem spitting out metadata files constantly? Mobile git sync stops being a convenience and starts being a liability.
The failure people actually run into isn't a clean error message. It's a sync that looks fine, a conflict that resolves silently in the wrong direction, a commit that hangs on a vault above some size nobody's ever pinned down. Restart the app and sometimes it clears itself up. Sometimes it doesn't, and now you're diffing files by hand trying to figure out what actually got written.
what you expect on desktop
Desktop Git vs Mobile Git: What Actually Happens
Aspect
Desktop Git
Mobile Git
Engine
Native git binary
JS reimplementation (isomorphic git)
Maturity
2+ decades hardened
Reimplemented object model and pack format
Large vault handling
Stable, native fs shortcuts
Chokes, no native fs shortcuts
Conflict handling
Explicit, visible
Can resolve silently in wrong direction
Commit outcome
Clean, exit code 0
Can hang mid commit, no size threshold known
Source: Based on article analysis of Obsidian Git plugin architecture
git add .
git commit -m "daily note 2026-08-12"
git push origin main
clean, fast, exit code 0
Recommended Hybrid Sync Setup Roles
DESKTOP
Git Plugin
Role: Version history only
MOBILE
Not Primary Sync
Role: Explicitly warned against
Git is a snapshot and merge system, triggered manually, not a real time sync layer on any platform.
Source: Based on article analysis of Obsidian Git plugin recommendations
what mobile is actually doing under the hood
isomorphic git walking the working tree in JS,
building pack files in memory, no native fs shortcuts
on a vault with 4000+ files this is not the same operation
There's also a definitional problem in how people describe this whole setup. Real time sync isn't something git does, on any platform, in any implementation. Git is a snapshot and merge system built around discrete commits that a human or a script has to trigger, not a continuous stream of changes flowing between devices. Calling a git based Obsidian setup "real time sync" describes what you wish it did, not what it actually does.
The instability warning in the plugin's docs isn't boilerplate caution. It's an accurate description of a JavaScript git reimplementation running into real limits on real vaults. Anyone running it on mobile as their primary sync path is trusting a mechanism the maintainer explicitly told them not to trust.
Verdict: treat the mobile warning as load bearing, not decorative. The docs aren't underselling the risk, they're naming it plainly, and skipping past that line is the actual root cause behind most of the horror stories sitting in the plugin's issue tracker.
Building A Hybrid Sync Setup That Holds Up
Once you accept that git was never meant to be your live sync layer, the setup actually gets simpler. Run the Git plugin on desktop only, purely for revision history and backup snapshots. Use something else entirely for device to device sync, Dropbox, Syncthing, iCloud Drive, whatever, they all handle this fine because they're built around continuous file watching instead of commit based snapshots.
Call it using each tool for what it was actually designed to do. Git answers "what did this file look like three weeks ago, and who changed it." File sync tools answer "is the version on my phone the same as the version on my laptop right now." Those are two different questions, and forcing one tool to answer both on a constrained mobile runtime is exactly where the instability comes from.
rough shape of the hybrid setup
desktop:
obsidian_git_plugin: enabled
purpose: version_history_and_backup
commit_schedule: on_close / hourly_auto_commit
mobile:
obsidian_git_plugin: disabled
sync_method: dropbox_or_syncthing
purpose: live_file_sync_across_devices
Where does GitSync fit in? Some analysts point to it as a mobile client sometimes suggested in place of the in app JavaScript git implementation. As of this writing it's a separate application that handles git operations natively outside the Obsidian mobile runtime, so it sidesteps the isomorphic git bottleneck rather than patching it. If you want git history on your phone without trusting the plugin's shaky mobile mode, that's the sturdier path. Still, think of it as a secondary read and light edit layer, not a replacement for a dedicated file sync tool moving your actual working files.
checking whether GitSync or the in app plugin is running your mobile sync
on iOS/Android, open Settings > Community Plugins > Git
if "mobile sync" shows enabled here, you are on the unstable path
GitSync runs as its own app, separate from the Obsidian plugin list
The setup that actually holds up is boring on purpose: desktop git for history, a real file sync tool for live state, GitSync bolted on only if you specifically want git visibility on your phone. Stacking all three jobs onto one mobile plugin is precisely the configuration its own maintainer tells you not to run.
Verdict: this hybrid arrangement isn't a compromise, it's just the tools doing what they were each built for. Anyone still routing live sync through the mobile plugin after reading this is picking convenience over durability, and the failure shows up eventually. Not maybe.
What Fails First When The Warning Gets Ignored
With the hybrid setup in place, it's worth naming exactly what the mobile plugin's failure modes look like, since these are the symptoms that tell you you made the right call. Vault size breaks first, and it breaks quietly. No official cutoff, no error saying "vault too large for mobile git," just sync operations that keep getting longer until they start timing out or hanging outright. A vault that syncs in two seconds on desktop can take noticeably longer on a phone running the same operation through JavaScript, and past a certain point "longer" turns into "never finishes."
Conflict resolution goes second, and it's worse because it fails silently instead of loudly. Desktop git hands you conflict markers you can see and resolve on purpose. The mobile reimplementation has, in practice, handled some conflict scenarios in ways nobody could predict, sometimes favoring one side of a merge with none of the clear prompting you'd get from the desktop binary. You find out when you notice a paragraph is missing from a note you edited on both devices.
Third is battery and background execution, more a platform limitation than a plugin flaw. Both iOS and Android aggressively suspend background activity to save power. A sync that was mid commit when you switched apps might get paused, killed, or resumed inconsistently, depending on the OS version and how aggressive its battery management is feeling that week.
- Vault size thresholds with no documented limit
- Silent conflict resolution instead of visible markers
- Background execution killed mid sync by the OS
- Pack file generation slowdowns on large media folders
- Inconsistent recovery after app restart, sometimes it clears on its own, sometimes you're stuck diffing files by hand
None of these are exotic edge cases. They're just the default behavior you get from running a from scratch git implementation inside a mobile runtime that was never built to host it, and the plugin's docs naming this outright is one of the more honest disclosures I've seen in a widely used Obsidian plugin. Most tools bury the caveat somewhere in a FAQ nobody reads. This one puts it in bold near the top.
Verdict: if you're already seeing longer sync times or edits going missing on mobile, that's not a bug to patch around. That's the documented ceiling of the approach, and the fix is architectural: move live sync off git entirely instead of poking at a setting inside the plugin.
So the sync that "appears to succeed" while your notes quietly diverge was never really a mystery. It's what happens when a JavaScript git reimplementation gets asked to do a job git was never built for, on a runtime it was never designed to run on. The plugin's own docs had the answer the whole time: keep git on desktop for history, hand live sync to a tool built for it, and add GitSync only if you want git visibility on your phone. Ignore that split and the divergence isn't a matter of if.