ghfs 0.0.3

# 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

```bash
cargo install ghfs --locked
```

### cargo-binstall

```bash
cargo binstall ghfs
```

### Homebrew (custom tap)

```bash
brew tap rgodha24/tap
brew install ghfs
```

### Shell installer

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

### Nix

```bash
nix run github:rgodha24/ghfs
```

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

```nix
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
ghfs service restart
```

or:

```bash
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:

```nix
{
  services.ghfs.enable = true;
}
```

- Linux: creates `systemd.user.services.ghfs`
- macOS: creates `launchd.agents.ghfs`

### macOS with nix-darwin + home-manager

```nix
{
  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)

```nix
{
  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:

```nix
{
  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; }
      ];
    };
  };
}
```