zen-fs-github

A ZenFS backend that maps file system operations to a GitHub repository via the GitHub REST API v3.

Read and write files in a GitHub repo directly from the browser or Node.js using ZenFS's standard fs API. Works seamlessly with zen-fs-sync for cross-backend synchronization.

Features

• Full file system API — read, write, delete, stat, readdir, and more, all backed by a real Git repository
• Synchronous reads — file contents are preloaded into memory on mount, so readFileSync works out of the box
• Async writes — writeFileSync and removeSync update the local cache immediately and queue API calls in the background
• Commit history — every write creates a new commit on the target branch
• mtime from commits — stat() returns the real last commit time for each file (cached after first lookup)
• GitHub Enterprise support — use a custom baseUrl for self-hosted GitHub instances
• Efficient downloads — raw file downloads use raw.githubusercontent.com for speed
• Browser & Node.js — works in both environments
• Sync-ready — compatible with zen-fs-sync for bi-directional sync with other backends

Installation

npm install zen-fs-github @zenfs/core

Usage

Basic setup with ZenFS

import { configure, fs } from '@zenfs/core';
import { Github } from 'zen-fs-github';

await configure({
  mounts: {
    '/repo': {
      backend: Github,
      token: 'YOUR_GITHUB_PERSONAL_ACCESS_TOKEN',
      owner: 'github-username',
      repo: 'repository-name',
      branch: 'main',             // optional, defaults to main
      disableAsyncCache: false,   // optional, preload file contents for sync reads
    },
  },
});

// Read a file
const content = fs.readFileSync('/repo/README.md', 'utf-8');

// Write a file
fs.writeFileSync('/repo/src/hello.ts', 'export const hello = "world";');

// List directory
const files = fs.readdirSync('/repo/src');

// Delete a file
fs.unlinkSync('/repo/src/old-file.txt');

With zen-fs-sync

import { SyncPair, SyncDirection } from 'zen-fs-sync';
import { Github } from 'zen-fs-github';

const githubFS = await Github.create({
  token: 'your-token',
  owner: 'your-name',
  repo: 'config-repo',
  branch: 'main',
});

// Sync local IndexedDB with a GitHub repo
const pair = new SyncPair(localFS, githubFS, {
  direction: SyncDirection.BiDirectional,
  pollIntervalMs: 300000, // 5 minutes
});

pair.watch();

GitHub Enterprise

import { Github } from 'zen-fs-github';

const gheFS = await Github.create({
  token: 'your-token',
  owner: 'your-org',
  repo: 'config-repo',
  baseUrl: 'https://github.your-company.com/api/v3',
});

API Reference

Github Backend Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | token | string | Yes | GitHub personal access token. Create one at GitHub Settings. Requires repo scope for private repos, or public_repo for public repos. | | owner | string | Yes | Repository owner (username or organization). | | repo | string | Yes | Repository name. | | branch | string | No | Target branch. Defaults to main. | | baseUrl | string | No | GitHub API base URL. Defaults to https://api.github.com. Set this for GitHub Enterprise. | | disableAsyncCache | boolean | No | If true, disables preloading file contents. Sync reads will throw EAGAIN until the file is read asynchronously. |

Methods

| Method | Description | |--------|-------------| | Github.create(options) | Static factory — creates and initializes the backend | | init() | Loads the repo tree and builds the in-memory index | | preloadContents() | Preloads all file contents into memory for sync reads | | ready() | Waits for initialization to complete | | sync() | Waits for all pending background write operations to finish | | getFileSha(path) | Returns the blob SHA for a file (useful for revision checks) |

How It Works

1. On mount, the backend fetches the repository's git tree and builds an in-memory Index of all files and directories.
2. By default, all file contents are preloaded into memory so that synchronous reads work out of the box.
3. Writes are translated to PUT requests against the GitHub Contents API (GitHub uses PUT for both create and update).
4. Each write creates a new commit on the target branch.
5. Raw file downloads use raw.githubusercontent.com for maximum efficiency.
6. Background sync — synchronous methods (writeFileSync, removeSync) update the local cache immediately and queue API calls. Call sync() to wait for all pending operations.

Differences from zen-fs-gitee

| Feature | zen-fs-github | zen-fs-gitee | |---------|--------------|--------------| | API Auth | Authorization: Bearer header | access_token query param | | Create File | PUT | POST | | Update File | PUT with sha | PUT with sha | | Raw Downloads | raw.githubusercontent.com | Gitee /raw/ endpoint | | Default Branch | main | master | | GitHub Enterprise | Supported via baseUrl | N/A |

Notes

• GitHub API rate limits: 5,000 requests/hour for authenticated users.
• Hard links and symbolic links are not supported (ENOSYS).
• The writeFileSync and removeSync methods update the local cache immediately and trigger background API calls.

License

MIT