What is iCloud git corruption?
iCloud git corruption is a specific form of repository damage caused by Apple's iCloud Drive syncing the contents of a .git directory. When Desktop & Documents sync is enabled (the default on most Macs), iCloud monitors files in ~/Desktop and ~/Documents and syncs them across devices. If a git repository lives in these folders, iCloud treats git's internal database files as ordinary documents. It creates conflict copies of branch refs (adding suffixes like "main 2"), evicts infrequently accessed object files and replaces them with .icloud placeholder stubs, and syncs lockfiles between machines. Developers can detect this corruption with five terminal commands that check for evicted files, conflict duplicates, and broken objects. The problem has been reported since at least 2017 on Apple Developer Forums, GitHub, and Stack Overflow, but Apple has never acknowledged it.
It takes 5 commands to know. It takes 5 days to recover.
If your Mac has Desktop & Documents sync turned on, and you keep any git repos in ~/Desktop or ~/Documents, iCloud may already be corrupting your repositories. Silently. Right now. While you're reading this.
This is not a theoretical risk. It is a documented problem that has been reported on Apple's own forums, on GitHub, on Hacker News, and on Stack Overflow since at least 2017. Apple has never acknowledged it.
iCloud is silently damaging your code projects. If you keep any coding projects in your Documents or Desktop folder, Apple's cloud sync is treating your version control files like regular documents. It does not know the difference. The damage is invisible until something breaks.
This has been happening since at least 2017. Apple has never warned developers about it and has never fixed it.
The failure surface is broad: any .git directory inside ~/Documents or ~/Desktop on a Mac with Desktop & Documents sync enabled is exposed. This includes agent workspaces, eval harnesses, and CI runner home directories on macOS.
Five commands. Run them now.
Open Terminal. Navigate to any git repo that lives inside an iCloud-synced folder. Run these five commands. If any of them produce unexpected output, your repo is compromised.
If command 1 returns any results, iCloud has replaced real files with placeholder stubs. If command 2 finds anything, iCloud has created conflict copies inside your git database. If command 3 reports missing or broken objects, your commit history is damaged. If command 4 shows .icloud files in the working tree, your project files are being evicted from disk.
If all five come back clean, you're safe. For now.
Here are 5 signs your project might already be damaged. You do not need to understand what each one means. If any of them sound familiar, your project needs attention.
If any of these sound familiar, keep reading. We will show you exactly what is happening and how to fix it.
Five detection signals for agent environments. Each maps to a specific iCloud corruption vector that affects workspace integrity.
In agent pipelines, signals 1 and 3 are the highest-severity: they cause silent eval failures because git operations return partial or incorrect data without raising exceptions in most wrapper libraries.
What iCloud actually does to your .git directory
iCloud Drive was designed to sync documents. Word files. PDFs. Photos. It was not designed to handle the internal structure of a git repository. But it tries anyway, and the results are destructive.
Here are the four specific ways iCloud corrupts git repos.
1. Conflict duplication of ref files
Git stores branch pointers as tiny files inside .git/refs/heads/. Each file contains a single SHA hash pointing to the latest commit on that branch. There must be exactly one file per branch.
When iCloud detects that the same ref file was modified on two machines, it does what it does with any document conflict. It keeps both copies and adds a numbered suffix. Your main ref becomes main and main 2. Git sees the file main 2 and tries to parse it. The result is a fatal error:
Git does not allow spaces in branch names. iCloud does not know this. One conflict resolution. One broken repo.
2. File eviction and placeholder substitution
iCloud automatically removes files from local disk to save space, replacing them with small .icloud placeholder files. This is a feature called "Optimize Mac Storage." It is promoted during setup and enabled on many Macs by default.
When iCloud evicts files from inside .git/objects/, those git objects vanish from disk. Git sees them as missing. The result:
Your commits still exist in the reflog. But the tree and blob objects they point to are gone. You cannot checkout those commits. You cannot diff against them. They are entries in a ledger pointing to empty shelves.
3. Sync backlog during rapid file changes
When you run git checkout to switch branches, git modifies dozens or hundreds of files in your working tree in under a second. iCloud sees every one of those changes and queues them for upload. If your internet connection cannot keep up, iCloud falls behind. While it is catching up, it litters your working tree with .icloud placeholder files for files it has not finished processing.
Run git status during this window and you see something like this:
If you accidentally commit those .icloud files, they end up in your remote repository. Other collaborators pull them. Now the corruption has spread.
4. Object database clobbering
Git's object database requires atomicity. When git writes a pack file or updates the index, it expects those operations to complete without interference. Cloud sync services do not respect this. As one developer explained on Hacker News: cloud sync services "happily clobber your git database records by arbitrarily choosing which file is 'better'" when conflicts arise. Git requires explicit merge conflict resolution. iCloud makes that decision for you, silently, and often incorrectly.
The result is pack files with bad checksums, index files that reference objects from a different branch, and a repository that appears to work until the fifth or sixth commit, when git finally notices the inconsistency and refuses to proceed.
iCloud was built for documents, photos, and files you open occasionally. It was not built for code projects. Here are the four things it does that break your projects.
1. It creates duplicate files
When two Macs try to sync the same file, iCloud does not know which version is correct. So it keeps both. It renames one by adding a number, like "main 2" or "config 3". Inside a code project, this breaks everything because the tools expect exact file names.
2. It removes files to save space
iCloud decides which files you have not used recently and removes them from your Mac to save storage. It replaces them with tiny placeholder files. When your code project needs those files, they are not there. You see errors about missing files or empty objects.
3. It syncs lock files between machines
When your code tools are working, they create temporary lock files to prevent conflicts. iCloud syncs these lock files to your other Macs. Now your other Mac thinks the project is locked and refuses to work with it.
4. It partially syncs large files
Git stores your project history in compressed files called pack files. These can be large. iCloud sometimes interrupts the sync partway through, leaving you with a half-written file. Your project history is now permanently incomplete on that machine.
Four corruption vectors, each targeting a different layer of git's internal architecture. Understanding these is critical for building resilient agent workspaces.
1. Ref conflict duplication
Impact on agents: any tool-use chain that reads HEAD or branch refs may resolve to different commits on different machines. Eval reproducibility breaks silently.
2. Object store eviction
Impact on agents: git log, git diff, and git show fail at arbitrary points in history. LLM context built from git history contains gaps. MCP servers that serve file history return errors.
3. Lock file propagation
Impact on agents: automated git operations (commit, fetch, rebase) fail with lock errors. Agent retry logic may compound the problem by creating additional lock files that also sync.
4. Pack file truncation
Impact on agents: this is the most destructive vector. Pack files contain the majority of objects in any non-trivial repo. Truncation can destroy hundreds or thousands of objects in a single event, making large portions of history permanently inaccessible.
The full diagnostic: healthy vs. corrupted output
Here is exactly what each command should look like when your repo is healthy, and what it looks like when iCloud has damaged it.
find . -name "*.icloud"find .git -name "* 2*"git fsck --fullgit statusgit for-each-refDangling objects are not always corruption. A few dangling blobs or commits from rebases and amended commits are normal. Look for missing objects and broken links. Those indicate actual data loss.
Here is a simple checklist. Green means safe. Red means your project needs attention.
Monitoring signal reference for agent workspace health checks. Integrate these into your CI pipeline or agent bootstrap sequence.
How widespread is this
There is no official statistic because Apple does not track it. But we can assemble the picture from what developers have reported.
The Apple Community thread warning about iCloud and git repos has 45 "Me Too" confirmations. The GitHub Desktop issue about the default clone path pointing to iCloud-synced folders was filed in 2017. Apple Developer Forums have multiple threads about Xcode projects corrupted by iCloud sync, going back to Xcode 11. The most recent thread, from December 2025, describes bad object errors, lost data, and randomly removed environment variables. It has zero replies from Apple.
The developer population at risk is large. According to recent surveys, roughly 30-57% of developers use macOS as their primary OS, depending on the survey. On every Mac sold, iCloud is offered during setup. Desktop & Documents sync is promoted as a default. Apple does not warn that this feature is incompatible with version control systems.
You are most at risk if you enabled Desktop & Documents sync (which captures ~/Documents and ~/Desktop) and who clone repos into those default locations. GitHub Desktop's default clone path on macOS pointed to ~/Documents for years.
This is not a rare bug. It affects every Mac that has Desktop & Documents sync turned on and has a code project in one of those folders. That is millions of Macs.
The problem has been reported on Apple's own support forums, on GitHub, on Stack Overflow, and on Hacker News. The earliest reports go back to 2017. Apple has never responded to any of them.
The exposure surface is larger than individual developer machines. Any macOS environment where repos land in iCloud-synced directories is vulnerable. This includes:
The problem compounds in multi-machine setups. A developer with a laptop and a desktop, both signed into the same Apple ID, has two machines independently corrupting the same repos. Agent environments that share a workspace via iCloud (intentionally or not) face the same compounding.
Why Apple hasn't fixed this (and probably won't)
The core issue is architectural. iCloud Drive is a file sync service designed for documents. It makes assumptions that are fundamentally incompatible with how git works.
- iCloud assumes files are independent. Git objects are not. A commit object points to a tree object, which points to blob objects. Remove one, and the chain breaks.
- iCloud resolves conflicts by keeping both copies. Git requires exactly one ref file per branch. Two copies with a numbered suffix is a broken repo, not a resolved conflict.
- iCloud evicts files to save disk space. Git needs its entire object database available locally to function. A placeholder stub is not a git object.
- iCloud syncs continuously in the background. Git operations like checkout, rebase, and merge modify many files rapidly. iCloud intercepts every write and tries to sync it, creating a race condition.
Fixing this would require Apple to detect .git directories and exclude them from sync behavior. The unofficial workaround is to append .nosync to folder names, which tells iCloud to skip them. But this is not documented, not reliable across macOS versions, and does not work retroactively on already-synced directories.
Apple has had at least 8 years to add .git to the iCloud exclusion list. They have not. There is no public bug tracker entry, no developer documentation warning, and no response on any of the forum threads where developers have reported this problem.
This is not an iCloud-only problem. Dropbox, Google Drive, and OneDrive all corrupt git repos through similar mechanisms. Any file sync service that treats .git as a normal folder will eventually break it.
This is not a bug Apple forgot to fix. It is a design choice. iCloud was built to sync documents, and it does that well. But code projects are not documents. They are complex systems of interconnected files that must stay exactly as they are. iCloud does not understand this distinction and probably never will.
Apple's business model depends on iCloud storage revenue. Warning developers to move code projects outside of iCloud would mean fewer files syncing, which means less storage used, which means less revenue. There is no financial incentive to fix this.
The root cause is an architectural incompatibility between document-sync heuristics and content-addressed storage systems. iCloud applies three assumptions that violate git's invariants:
What to do about it
The immediate fix: move your repos
Create a directory outside of iCloud sync and move your repositories there.
~/Projects is not inside ~/Documents or ~/Desktop, so iCloud will not sync it. Your repos are safe from conflict duplication, file eviction, and sync backlog. This is the simplest and most reliable fix.
The remaining problem: backups
Moving repos out of iCloud solves the corruption problem. But it creates a new one. Those repos are no longer backed up anywhere. If your hard drive fails, if your Mac is stolen, if you accidentally delete a directory, your work is gone.
Pushing to GitHub is one layer. But GitHub only stores committed work. Your uncommitted changes, your stashes, your work-in-progress branches that you have not pushed yet. Those exist only on your machine.
This is the problem we built DevSafe to solve. Encrypted backups of your entire git repository, including uncommitted work, pushed to your own cloud storage. No sync conflicts. No file eviction. No corruption. Your repos stay safe without iCloud ever touching them.
Private does not mean encrypted. GitHub's private repos are readable by GitHub employees, law enforcement, and anyone who compromises GitHub's infrastructure. DevSafe encrypts before upload. Your storage provider never sees your code.
The checklist
Here is what to do this week.
- Run the 5 diagnostic commands on every repo in an iCloud-synced folder. Right now.
- Move all repos to
~/Projectsor another non-synced directory. - Disable Desktop & Documents sync if you do not need it. System Settings > Apple Account > iCloud > iCloud Drive > turn off "Desktop & Documents Folders."
- Set up real backups. Push to GitHub for committed work. Use DevSafe for encrypted, complete backups of everything, including what you have not committed yet.
- Tell your team. If anyone on your team uses macOS with iCloud sync, they are probably affected. Share this post.
Five commands to diagnose. Five minutes to move. Five years of work you could lose if you don't.
The fix is simple: move your code projects out of any folder that iCloud syncs. Here is exactly how to do it.
Step 1: Create a safe folder
Step 2: Move your projects
Step 3: Update your tools
Step 4: Verify your projects still work
Remediation protocol for agent environments and developer workstations.
Immediate: isolate repos from sync
Preventive: agent bootstrap checks
Recovery: corrupted workspace
Frequently asked questions
How do I check if iCloud is corrupting my git repos?
Run these commands in any git repo inside an iCloud-synced folder: find .git -name "*.icloud" to check for evicted files, find .git -name "* 2" to find conflict duplicates, git fsck --no-dangling to verify object integrity, find . -name "*.icloud" -not -path "./.git/*" to check working tree files, and git status to confirm normal operation. If any command produces unexpected output, your repository may be corrupted.
What does iCloud do to .git directories?
iCloud causes four types of damage to .git directories: it creates conflict duplicates of ref files (adding numbered suffixes like 'main 2'), it evicts git objects from disk and replaces them with .icloud placeholder stubs, it syncs lockfiles between machines causing deadlocks, and it modifies file timestamps which triggers unnecessary re-indexing. These changes are silent and only surface when git operations fail.
How do I stop iCloud from syncing my git repos?
Move your git repositories out of iCloud-synced folders (~/Desktop, ~/Documents, or any folder inside ~/Library/Mobile Documents). Store repos in a non-synced location like ~/Projects or ~/Code. You can also disable Desktop & Documents sync in System Settings > Apple Account > iCloud > iCloud Drive, but this affects all files in those folders. For backup, use a git-aware backup tool instead of filesystem sync.
No. Apple does not let you exclude individual folders from Desktop & Documents sync. It is all or nothing. You either sync both Desktop and Documents, or neither. The workaround is to keep your code projects in a folder that is not inside Desktop or Documents.
It will stop new damage from happening, but it will not fix damage that has already occurred. If your project is already corrupted, you will need to re-clone it from GitHub or wherever you originally downloaded it. Turning off sync just prevents future corruption.
Yes. Any cloud sync service that monitors folders and syncs files will cause the same problems with code projects. Dropbox, Google Drive, OneDrive, and iCloud all have this issue. The solution is always the same: keep code projects outside of synced folders.
The editor does not matter. What matters is where your project folder is. If your project is inside Documents or Desktop and iCloud sync is on, you are affected regardless of which editor you use. Move your project to a safe folder and it will work the same in any editor.
Open System Settings, click your name at the top, click iCloud, click iCloud Drive, then click the Options button next to it. If "Desktop & Documents Folders" has a checkmark, sync is on. On most Macs, it is on by default.
If you pushed your code to GitHub, GitLab, or another remote before the corruption happened, you can recover by cloning a fresh copy. If you never pushed, check if iCloud keeps a version in iCloud.com (sign in and look in iCloud Drive). Time Machine backups may also have an uncorrupted copy. If none of those work, the lost work may not be recoverable.
Yes. Run find .git -name "*.icloud" -o -name ".*.icloud" for eviction detection and find .git -regex ".* [0-9]" for conflict duplication. Both are O(n) on the .git directory size and complete in under 1 second for repos up to 1GB. Integrate these into agent bootstrap or pre-operation health checks. A nonzero result from either command means the repo is compromised.
Yes, if the MCP server reads from a git repo in a synced directory. MCP servers that use git plumbing commands (cat-file, rev-list) to serve file contents will fail on evicted objects with no clear error propagation to the LLM client. The LLM receives either an error or incomplete context, both of which degrade response quality silently.
No. .gitignore tells git which files to ignore. It has no effect on iCloud, which operates at the filesystem level independently of git. iCloud does not read or respect .gitignore. There is no iCloud-level equivalent of .gitignore for excluding specific directories from sync. The only solution is physical path isolation.
Docker containers on macOS are isolated from iCloud sync because the container filesystem is a Linux VM disk image, not a macOS directory. Repos inside containers are safe. However, if you mount a host directory from ~/Documents or ~/Desktop into the container, the mounted path is still subject to iCloud sync on the host side. Use bind mounts from non-synced host paths only.
git bundle create reads from the object database, not the filesystem. If the object database is intact (no evicted objects, no truncated packs), the bundle will be valid even if working tree files are corrupted. This is why git-aware backup tools that operate at the object level are immune to iCloud corruption. The bundle is a self-contained transport format that captures the entire reachable object graph.
Git worktrees share the same .git object store. If the main repo is in a synced directory, all worktrees (even those in non-synced paths) are affected because they reference the same object database via the .git file pointer. Conversely, if the main repo is in a safe path, worktrees in synced paths only risk working tree file eviction, not object store corruption.