GitFar: GitHub-compatible APIs from git on disk

GitFar started with a joke that was also an architecture decision: change three letters in the API origin and keep everything else boring. Point a GitHub-speaking client at api.gitfar.com instead of api.github.com, and let a small facade answer the familiar REST shape from git repositories on our own disks.

That is the whole pitch, but the consequences are large. Rate-limit clocks stop being the center of the design. Hosted search windows stop deciding how far a playground can page. Storage tiers stop being part of the mental model. The remaining limit is the machine doing the work, the git repositories it can read, and the compatibility surface the facade deliberately implements.

The rule

The most important line in the GitFar runbook is blunt: git repository state is authoritative; GitFar has no repository database. That rule prevents a whole class of drift. There is no separate repository catalog to reconcile, no metadata cache that can lie, and no separate auth store pretending to be the product. The served repositories under the GitFar root are the state.

For the RTCode playground, that means the API facade can behave like a GitHub-compatible service without becoming a second forge. Read operations inspect the repository. Write operations update the repository. Debugging starts with git status and git log, not a hidden application table.

Small on purpose

GitFar is implemented with Bun and the git CLI. The maintained source is intentionally narrow: browser-compatible Web APIs first, Bun APIs where they fit, and only a small allowed slice of node: APIs for filesystem and path work. The runbook is explicit about not adding third-party JavaScript packages without a real justification.

That constraint is not aesthetic minimalism for its own sake. GitFar sits on a sensitive boundary: authenticated clients send repository operations to a service that shells out to git. Keeping the service small makes it inspectable. Keeping dependencies at zero means there is less supply-chain surface to explain. Keeping git as the backend keeps the operational model legible.

Compatibility first, extensions explicit

The default contract is GitHub REST compatibility. That includes endpoint shapes, JSON expectations, strong validators where they matter, and the ordinary behavior a GitHub-oriented client expects. When GitFar needs playground-specific behavior, it does not quietly mutate those semantics. It uses explicit x-gitfar-* headers.

That shows up in code search and ownership filtering. The playground can ask for latest-commit ownership checks, force a repository and path, or request an unbounded search window using GitFar-specific headers. A normal GitHub-compatible request does not inherit those playground rules by accident.

Why the search window matters

GitHub's search API has a familiar hard edge: the 1,000-result window. That is reasonable for a global hosted product, but it is awkward when the dataset is your own repository and the caller is an internal playground that needs to keep walking. GitFar keeps GitHub-compatible behavior as the default, then lets the playground opt into x-gitfar-search-window: unbounded.

It still has engineering guards. The public site calls out sane limits such as blob scan and file-pass bounds. Those are not account tiers, quota clocks, or commercial ceilings. They are local safety rails so the service remains predictable.

Cloudflare at the edge, git at the center

The public endpoint is Cloudflare-fronted. Clients speak HTTPS to the edge, and the origin service answers on the GitFar port from the runtime directory. The raw host has its own job: return active file types as displayable text/plain so raw links show source instead of executing it in the browser.

There are details here that only infrastructure people enjoy until they break. Cloudflare can transform compressed JSON in ways that weaken strong ETags, so GitFar sends Cache-Control: private, max-age=60, s-maxage=60, no-transform. The point is not clever caching. The point is preserving the wire behavior that compatibility tests expect.

Tested against the thing it imitates

GitFar carries compatibility tooling next to the service. The playground compatibility report compares GitHub and GitFar across the calls the playground depends on: repository metadata, contents JSON, raw contents, commits, compare, refs, code search, commit search, and write paths. Write checks use temporary branches and clean up after themselves instead of advancing main.

There is also a broader harness for comparing forge behavior, but the important daily loop is narrower: if a playground depends on a GitHub-shaped call, the report should be able to prove GitFar still answers it correctly.

What GitFar is not

GitFar is not trying to become GitHub. It is not a social layer, an issue tracker, an actions runner, or a universal forge clone. It is an API facade for a specific class of clients that already know how to speak GitHub REST and mainly need repository truth, code search, contents, refs, commits, and writes.

That narrower ambition is what makes the project work. The service can stay small. The storage model can stay honest. The compatibility story can be tested instead of hand-waved. And the operational burden stays close to the tool everyone already understands: git.

Getting far by staying close

The nice thing about GitFar is that its pun is also its product philosophy. It gets far by staying close to the repository. It keeps the API surface close to GitHub where clients need it. It keeps the source of truth close to the disk. It keeps extension behavior close to explicit headers.

Three letters changed in the origin. The rest of the system is deliberately conservative: Bun, git, Cloudflare, compatibility reports, and repositories that remain the thing they have always been: the source of truth.