Skip to content
githosted

Repos

A githosted repo is a real Git repo. Same objects, same refs, same protocol. The SDK is one way in. git push is another. Both produce real commits in the same history.

repo.write("output.json", data, message="Run #42")

is equivalent to:

Terminal window
git clone https://gw_…@githosted.dev/<ws>/<repo>.git
cd <repo>
echo '...' > output.json
git add output.json && git commit -m "Run #42"
git push

— except the SDK version doesn’t need a working directory, doesn’t shell out to git, and works from any runtime where you can make HTTPS calls (a Lambda, an agent container, a Cloudflare Worker, a shell script).

What you can do

Section titled “What you can do”

Through the SDK:

  • Read files at any ref: repo.read("path", ref="HEAD")
  • Write files: repo.write("path", contents, message="…") — produces one commit
  • List: repo.ls("path")
  • Delete: repo.delete("path", message="…")
  • Transactions: change multiple files in one atomic commit
  • History: repo.log(), repo.diff(base, head)
  • Branches: repo.create_branch, repo.list_branches, repo.merge

Through plain Git over HTTPS, with a gw_ or gr_ token as the HTTP basic password: anything you’d do against any other Git host.

When to reach for the SDK vs Git

Section titled “When to reach for the SDK vs Git”

Use the SDK when you’re writing programmatic code that doesn’t already speak Git — agents, app backends, scripts. Three lines to write a file beats git clone ceremony every time.

Use plain Git when you’re a human at a terminal, or when an existing tool already shells out (Docker build contexts, CI runners, anything that expects a .git directory).

Both paths produce real commits in the same history. Pick the ergonomic one.

Yours to move

Section titled “Yours to move”

Because every repo here is a real Git repo, taking it elsewhere is a one-liner:

Terminal window
git clone --mirror https://githosted.dev/<ws>/<repo>.git
git --git-dir=<repo>.git remote add elsewhere <url>
git --git-dir=<repo>.git push --mirror elsewhere

--mirror carries every ref, every tag, every branch — exactly what you’d push to a fresh remote. No vendor-specific export format, no API to script around.

Two-way sync to GitHub and GitLab is on the roadmap; until then the export above plus a cron job is the supported path for “keep a mirror somewhere else.”

Names and IDs

Section titled “Names and IDs”

Like workspaces and orgs, repos have a slug (URL-friendly) and a stable ID (rp_…). The SDK takes either. URLs in the dashboard use the slug; programmatic code that needs to survive renames should hold onto the ID.