GHFS is a macOS application that mounts your GitHub repositories as a read-only virtual filesystem using FSKit. Browse repository contents as if they were local directories — repositories are cloned on demand, and file reads are served from the GitHub API while the clone completes in the background.

Key features:

• Self-contained, no external dependencies required (macFUSE, git, gh, etc.)
• Mount-time repository discovery from your GitHub account, plus opt-in public repository search
• On-demand repository cloning with automatic background refresh of cloned repositories

• macOS 26.4 or later
• Xcode (for building from source)

The easiest way to use GHFS is to download a prebuilt binary from the latest release on GitHub. Open the downloaded .dmg and drag GHFS.app into your Applications folder. Releases are signed with a Developer ID certificate and notarized by Apple.

If you'd rather build from source, see Building below.

A source build needs a Credentials.xcconfig file containing your GitHub OAuth app credentials (so GHFS can authenticate users) and your Apple Developer Team ID (so Xcode can sign the app and the FSKit extension). Prebuilt binaries ship with all of these baked in, so this step only applies when building from source.

Start by copying the template:

cp Credentials.xcconfig.template Credentials.xcconfig

Credentials.xcconfig is gitignored. The OAuth values are consumed at build time by a Run Script phase that generates GeneratedSecrets.swift — the app will fatal-error on launch if any OAuth value is missing or still set to the placeholder. The Team ID flows into DEVELOPMENT_TEAM via the project's base configuration, so a missing or wrong value will cause code-signing to fail at build time.

Then fill in the three values as described below.

1. Go to https://github.com/settings/developers → OAuth Apps → New OAuth App.

2. Fill in the form:

   • Application name: anything you like, e.g. GHFS (local build)
   • Homepage URL: any valid URL
   • Authorization callback URL: ghfs://oauth-callback — must match exactly. This is the custom URL scheme the app listens on for the OAuth redirect.
   • Leave Enable Device Flow unchecked.

3. Click Register application. On the next page, note the Client ID, then click Generate a new client secret to create a client secret. Copy the secret immediately — GitHub will only show it once.

4. Paste the two values into Credentials.xcconfig:

   GHFS_OAUTH_CLIENT_ID = <your client id>
   GHFS_OAUTH_CLIENT_SECRET = <your client secret>
   

This is your 10-character Apple Developer Team ID. You need an Apple Developer account (free or paid) signed into Xcode; the free tier is sufficient for local development.

To find your Team ID, either:

• Sign in at https://developer.apple.com/account → Membership details. The Team ID is listed there.

• Or, from the terminal with an active signing identity in your keychain:

  security find-identity -v -p codesigning

  The parenthesized suffix on each Apple Development: … / Developer ID Application: … line is your Team ID.

Paste it into Credentials.xcconfig:

GHFS_DEVELOPMENT_TEAM = <your 10-character team id>

Build the app using the provided build script:

Scripts/build.sh

The built app is placed in out/GHFS.app. The script also handles code signing validation and FSKit extension registration.

On the first build, libgit2 is compiled from source automatically (one-time setup).

Run the integration test suite:

Scripts/test.sh

Tests exercise the live GHFS mount against the GitHub API and verify behavior via post-run log analysis. The test runner builds the app, launches it, waits for the filesystem to mount, and runs swift test against it.

Before running tests, ensure:

1. The FSKit extension is enabled in System Settings > Login Items & Extensions > By Category > File System Extensions (enable "GHFS”).
2. You have completed onboarding (signed in with GitHub).

GHFS provides the following settings and repository-selection controls in the app's Settings window:

This project is licensed under the MIT License. See LICENSE.md for details.

Created by Indragie Karunaratne