GitDrive

Your private GitHub repos as a drive in Finder. Files download when you open them and can be removed from your Mac without leaving the cloud.

Screenshots

Features

• Lives in Finder. GitDrive appears in the Finder sidebar like iCloud Drive or Dropbox, built on Apple's File Provider framework.
• Files on demand. Everything is listed right away. A file downloads only when you open it.
• Frees up space. Right-click and choose Remove Download, or use Free Up Space in the menu bar. macOS can also remove downloads on its own when the disk is low.
• Private by default. Every top-level folder is its own private GitHub repo named drive-<folder>.
• Optional end-to-end encryption. Post-quantum (ML-KEM-768 + X25519) with deduplication and compression. GitHub sees random data: no names, no folder layout, no file sizes. Needs macOS 26. See docs/ENCRYPTION.md.
• Real git history. Each save is a commit, so every old version stays recoverable on GitHub.
• Large files with Git LFS. Optional: files over a size you choose go to Git LFS, up to 2 GB each.
• Keeps file dates. Modification dates are saved in the repo, so every Mac shows the same dates.
• Works with other edits. Changes made on github.com or from a clone show up in Finder within a minute. Edits on both sides keep both copies.
• Menu bar app. Sync status, folder sizes, pause, launch at login.
• No local clones. GitDrive talks to the GitHub API directly, so files are never stored twice.

Extras

Optional features, each with a switch in Settings → Extras:

• Finder: Quick Look and thumbnails without downloading, search for files that aren't downloaded (including encrypted names), conflict badges.
• History: Show Versions, Recently Deleted, a conflict viewer with side-by-side diff, a duplicate finder, a monthly bit-rot check.
• Safety: Touch ID or a passcode for encrypted folders, decoy folders behind a duress passcode, a ransomware tripwire with one-hour rollback.
• Modes: Photos (timeline, map, albums), Notes (Markdown with backlinks), daily versioned backups of Mac folders.
• GitHub: publish a folder as a website, compress videos or make PDFs with GitHub Actions, open a folder in Codespaces.

Details and defaults are in docs/EXTRAS.md.

How it works

The File Provider extension serves the drive to Finder. It keeps a small SQLite index of every file and folder, turns your edits into commits through the GitHub Git Data API, and pulls in remote changes by comparing trees. The menu bar app handles sign-in and asks the extension to check for changes every minute.

More detail is in docs/ARCHITECTURE.md.

Install

GitDrive is free and installs from source. You need macOS 14 or later, Xcode (free), and an Apple ID added to Xcode under Settings → Accounts. A free Apple ID works; no paid developer account needed.

git clone https://github.com/deeeeone/gitdrive.git
cd gitdrive
./scripts/install.sh

The script installs XcodeGen if needed, finds your signing team, builds GitDrive, copies it to /Applications and opens it. It takes a minute or two the first time.

brew install xcodegen
cp Config/Local.xcconfig.example Config/Local.xcconfig

xcodegen generate
open GitDrive.xcodeproj

[!NOTE] There are no prebuilt downloads. macOS only loads File Provider extensions from apps signed by a developer team, so each person builds GitDrive with their own Apple ID. Builds made this way run on the Mac that built them.

First run

1. Click the cloud icon in the menu bar.
2. Sign in. Choose Sign in with GitHub (if the build has an OAuth Client ID), or paste a personal access token with the repo and delete_repo scopes. Without delete_repo, deleting a top-level folder fails unless you switch it to archive.
3. If macOS asks, turn on GitDrive in System Settings → General → Login Items & Extensions → File Providers.
4. Click Open in Finder. Make a folder at the top level and GitDrive creates a private repo for it.

Already have repos you want in the drive? Open Settings → Folders → Your other repos and choose Add to Drive.

Limits and fair use

GitHub is built for source code, not as a general file host, so keep these in mind:

Please read GitHub's Acceptable Use Policies before storing large amounts of non-code data.

Privacy and security

• Your GitHub token is stored only in the macOS Keychain, shared between the app and its extension.
• Repos GitDrive creates are always private. Turn on encryption and GitHub can't read them at all.
• Your encryption key stays in iCloud Keychain. Each encrypted repo holds only the public key.
• Deleting a top-level folder deletes its repo, after Finder asks. Choose Settings → General → Top-level folders → Archives its GitHub repo if you'd rather keep a read-only copy on GitHub.
• Deleting anything else is a commit, so it can be recovered from the repo's history.
• The only force-push is Compact History, which asks first.
• No analytics, no telemetry, no servers other than GitHub.

Found a security problem? See SECURITY.md.

Roadmap

• Git LFS for files over 100 MB
• Modification dates stored in the repo
• Moving folders between top-level folders
• End-to-end encryption with hidden file structure
• Shared folders (repos you collaborate on)
• Decrypting a folder back to a readable repo
• Lock badge on encrypted folders in Finder
• Signed and notarized release builds

FAQ

Does it work offline? Downloaded files open and save as usual. GitDrive uploads your changes when you are back online.

Can I use the repos with normal git? Yes. They are ordinary repos. Clone them, push to them, and GitDrive picks up the changes.

What happens if I uninstall? Nothing on GitHub changes. Sign out first to remove the downloaded copies from your Mac.

Why one repo per folder? It keeps each repo small, lets you share or archive folders separately, and keeps the API traffic for one folder independent of the others.

Contributing

Contributions are welcome. Read CONTRIBUTING.md for setup, code style and how to run the tests. Please follow the Code of Conduct.

License

GitDrive is released under the MIT License.

Acknowledgements

• GRDB.swift for SQLite
• XcodeGen for the project file
• Apple's File Provider framework