ghfs

Coding Agents are really good at using example code and documentation for libraries

Mount GitHub repositories as a local filesystem.

ghfs daemon is the foreground daemon entry point. It does not daemonize itself; use your platform service manager (systemd or launchd) for backgrounding and restarts.

Install

Cargo

cargo install ghfs --locked

cargo-binstall

cargo binstall ghfs

Homebrew (custom tap)

brew tap rgodha24/tap
brew install ghfs

Shell installer

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/rgodha24/ghfs/releases/latest/download/ghfs-installer.sh | sh

Nix

nix run github:rgodha24/ghfs

For managed per-user daemon setup, use the Home-Manager module documented below and set:

services.ghfs.enable = true;

Release Automation Setup

Release CI is generated by dist and publishes:

• GitHub release artifacts (for cargo-binstall and shell installer)
• Homebrew formula to rgodha24/homebrew-tap
• crates.io package via a custom publish job

Required repository secrets:

• HOMEBREW_TAP_TOKEN: PAT with write access to rgodha24/homebrew-tap
• CRATES_TOKEN: crates.io API token for publishing ghfs

Release trigger:

git tag v0.0.1
git push --tags

Non-Nix Service Management

For non-Nix installs, use ghfs service to install/manage a user service:

ghfs service install
ghfs service status

Linux runtime requirements: /dev/fuse must exist and a fusermount helper (fusermount3 or fusermount) must be installed.

Available commands:

ghfs service install [--no-start]
ghfs service uninstall
ghfs service start
ghfs service stop [--force]
ghfs service restart
ghfs service status
ghfs service logs

Cache maintenance:

ghfs gc

ghfs gc reconciles daemon state with cache contents and clears stale metadata.

ghfs service install is idempotent. Running it again rewrites service config with the current binary path and restarts the daemon.

Updating ghfs

After updating the ghfs binary, use one of:

ghfs service restart

or:

ghfs service install

restart is the lightweight option when binary path is unchanged. install always works (it rewrites service files, then starts/restarts).

Nix Flake Outputs

This flake exports:

• packages.<system>.default - ghfs package
• devShells.<system>.default - development shell
• homeManagerModules.default - home-manager module (Linux + macOS)
• nixosModules.default - NixOS module (system-level Linux daemon)

Both module wrappers default services.ghfs.package to self.packages.${pkgs.system}.default, so the daemon binary always comes from this flake.

Home-Manager Module (macOS + Linux)

Enable per-user service:

{
  services.ghfs.enable = true;
}

• Linux: creates systemd.user.services.ghfs
• macOS: creates launchd.agents.ghfs

macOS with nix-darwin + home-manager

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nix-darwin.url = "github:LnL7/nix-darwin";
    home-manager.url = "github:nix-community/home-manager";
    ghfs.url = "github:rgodha24/ghfs";
  };

  outputs = { nix-darwin, home-manager, ghfs, ... }: {
    darwinConfigurations.myMac = nix-darwin.lib.darwinSystem {
      modules = [
        home-manager.darwinModules.home-manager
        {
          home-manager.sharedModules = [ ghfs.homeManagerModules.default ];
          home-manager.users.myuser = {
            services.ghfs.enable = true;
          };
        }
      ];
    };
  };
}

NixOS with home-manager (per-user daemon)

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    ghfs.url = "github:rgodha24/ghfs";
  };

  outputs = { nixpkgs, home-manager, ghfs, ... }: {
    nixosConfigurations.myBox = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        home-manager.nixosModules.home-manager
        {
          home-manager.sharedModules = [ ghfs.homeManagerModules.default ];
          home-manager.users.myuser = {
            services.ghfs.enable = true;
          };
        }
      ];
    };
  };
}

NixOS Module (system-level daemon)

Enable system daemon:

{
  inputs.ghfs.url = "github:rgodha24/ghfs";

  outputs = { nixpkgs, ghfs, ... }: {
    nixosConfigurations.myBox = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ghfs.nixosModules.default
        { services.ghfs.enable = true; }
      ];
    };
  };
}