gitbrella is a command-line tool that finds and repairs damage in git repositories kept inside cloud-synced folders. It checks a repository without changing it and without downloading anything from the cloud, repairs what has exactly one right repair, and ends the problem for good by moving the .git directory out of the synced folder.
The problem
iCloud Drive, Dropbox, OneDrive, Google Drive and Syncthing sync files one by one, while git expects its .git directory to change as a whole. Repositories in synced folders therefore pick up familiar damage:
- conflict copies such as
.git/index 2orrefs/heads/main 2 - a missing index next to a leftover
index.lock - object files that exist only in the cloud and never reached the disk
- an index rebuilt empty, so the next commit records every file as deleted
Git’s own FAQ advises against keeping a repository in a synced folder, yet defaults keep putting them there: macOS Desktop and Documents in iCloud, Windows folder backup to OneDrive, or Documents/GitHub. The damage usually stays silent until a wrong commit has already been made.
Product goals
- Never write to the repository and never download cloud-only files during a check
- Stay quiet on healthy repositories; treat a lock as damage only when no running git could hold it
- Repair only what has one right answer and hand the rest to the user with the command to run
- Keep every change reversible
- Give commit hooks and AI agents stable exit codes and versioned JSON output
Commands
| Command | What it does |
|---|---|
gitbrella check | reports the damage; read-only |
gitbrella fix | repairs what has one right answer |
gitbrella move-out | moves .git out of the synced folder for good |
gitbrella undo | reverses the newest fix or move |
gitbrella history | lists the changes made on this device |
gitbrella hook --for claude|codex | guards AI agents’ tool calls |
check typically finishes in under a second. Exit status 0 means healthy, 1 means damage was found, and 2 means the check could not run. Without --apply, fix and move-out only print their plan.
Main capabilities
Read-only checks
During a check, git runs with optional locks off (GIT_OPTIONAL_LOCKS=0), automatic gc and maintenance disabled, and only commands that read. On macOS the tool turns off on-demand cloud downloads for its own process; if the operating system refuses, the check does not run. Partial clones never fetch missing objects. End-to-end tests for the risky cases record each file’s size, modification time and inode before and after the check and require them to match.
Safe repair and a lasting fix
fix repairs cases with one right answer, such as an index copy identical to HEAD, and reports ambiguous cases unchanged together with the command to run. move-out moves .git out of the synced folder and leaves a .git file pointing at it, so the sync client keeps carrying the files while git history stays outside sync.
Commit hooks and agent guards
As a pre-commit hook it blocks commits in a damaged repository, most importantly preventing an emptied index from recording every file as deleted. It works with pre-commit, lefthook, husky and Overcommit. gitbrella hook --for claude|codex speaks the hook protocols of Claude Code and Codex: in a damaged repository it stops git commands that write and writes into .git, while reading, editing files and repairing still go ahead.
Installation
It runs on macOS and Linux, amd64 and arm64, and requires git 2.31 or newer.
brew install aliyilmazco/tap/gitbrella
go install github.com/aliyilmazco/gitbrella/cmd/gitbrella@latest
Each release ships a SHA-256 checksum list, a keyless cosign signature, an SPDX SBOM for each archive, and a GitHub build-provenance attestation.
Limits
- Windows and OneDrive on Windows are untested.
- Conflict copies made by iCloud itself across two devices were not reproduced in tests; detection is verified with copies that follow the same naming.
fixrepairs only damage with one right answer. The lasting fix ismove-out.
Links
- GitHub repository
- Latest release: v1.0.2
- Homebrew:
brew install aliyilmazco/tap/gitbrella - License: MIT
- README available in 18 languages
Engineering notes
The hard part of a tool like this is not finding damage but finding nothing on a healthy repository. Locks held by running git processes, git’s temporary files and other tools’ files inside .git must not count as damage. Run against 89 healthy working repositories, it reported no damage. The same care applies to repairs: a change is made automatically only when it can be undone and has exactly one right outcome.