ghfs

ghfs

The GitHub Filesystem (GHFS) is a user space filesystem that overlays the GitHub API. It allows you to access repositories and files using standard Unix commands such as ls and cat.

Fork of benbjohnson/ghfs

Install

To use ghfs, you'll need to install Go. If you're running macOS then you'll also need to install macFUSE.

To run ghfs:

$ go install github.com/broady/ghfs@latest
$ ghfs -h

Or run without installing (npx/uvx-equivalent):

$ go run github.com/broady/ghfs@latest ~/github.com

Now you can read data from the GitHub API via the ~/github.com directory.

Usage

Basic Usage

GHFS uses GitHub URL conventions for pathing. For example, to go to a user you can cd using their username and list their repos:

$ ls ~/github.com/broady/ | grep ghfs
ghfs

To go to a repository, you can use the username and repository name:

$ cd ~/github.com/broady/ghfs

Once you're in a repository, you can list files using ls and you can print out file contents using the cat tool.

$ cat ~/github.com/broady/ghfs/LICENSE | head -1
The MIT License (MIT)

Configuration

GitHub Authentication

To authenticate with GitHub and increase API rate limits, pass your personal access token:

$ ghfs -token=YOUR_TOKEN ~/github.com

Or use the GitHub CLI to automatically provide your token:

$ ghfs -token $(gh auth token) ~/github.com

Caching

GHFS uses a two-tier cache by default: an in-memory LRU cache backed by a disk cache. This allows fast repeated access while persisting responses across sessions.

Configure caching with the following flags:

# Default: 128 MB memory, 1 GB disk cache at ~/.cache/ghfs
$ ghfs ~/github.com

# Larger memory cache (500 MB) and disk cache (5 GB)
$ ghfs -cache-mem-mb=500 -cache-disk-mb=5120 ~/github.com

# Custom cache directory
$ ghfs -cache-dir=/tmp/my-cache ~/github.com

# Disable caching entirely
$ ghfs -no-cache ~/github.com

Force cache refresh:

To force immediate revalidation with GitHub (for example, to see recent changes), send SIGUSR1 to the ghfs process:

# The command is shown in the startup logs, or find the PID:
$ kill -USR1 $(pgrep ghfs)

This clears the revalidation suppression cache. The next filesystem operation will check GitHub for updates, even if the cached data hasn't expired yet.

Logging

Control the log level using the GHFS_LOG_LEVEL environment variable. Valid levels are debug, info, warn, and error. Defaults to info.

# Enable debug logging
$ GHFS_LOG_LEVEL=debug ghfs ~/github.com

# Suppress warnings
$ GHFS_LOG_LEVEL=error ghfs ~/github.com

TODO

• Handle rate limits and 429s properly.