Push and pull with Git

Push Git commits into a disk, edit its files through the filesystem API, and fetch committed changes back with an ordinary Git client. Create the demo disk first using the quickstart. A disk corresponds to one repository; Git branch names correspond to wabe Disk branches.

Push a repository

git -c "http.extraHeader=Authorization: Bearer YOUR_PROJECT_API_KEY" \
  push "https://api.wabe.sh/v1/disks/demo/git" HEAD:refs/heads/main

Push publishes all accepted branch changes atomically and waits for a WAL flush before acknowledging success. A concurrent change or uncommitted file edit in a target branch returns a conflict. Commit those edits before pushing. File downloads and existing commit views remain consistent during publication.

Clone and pull

git -c "http.extraHeader=Authorization: Bearer YOUR_PROJECT_API_KEY" \
  clone "https://api.wabe.sh/v1/disks/demo/git" wabe-copy
cd wabe-copy
git -c "http.extraHeader=Authorization: Bearer YOUR_PROJECT_API_KEY" \
  pull --ff-only

Git sees committed state. Uncommitted filesystem changes stay in their independently writable branches. Commit a change with POST /v1/disks/demo/commits before fetching it. message accepts a title and body separated by a blank line. Imported commit bytes, SHA-1 IDs, parents, author metadata and signatures are retained. Native commits receive deterministic Git metadata when exported. Merge commits retain every parent.

Executable modes and symlinks survive Git round trips. Within wabe Disk, a symlink is exposed as a file containing its link target; filesystem operations do not follow it. Metadata includes the octal mode as a JSON integer (33188, 33261 or 40960). Git clients do not materialize empty directories.

Endpoint, parameters and response

Method	Endpoint	Parameters	Response
GET	/v1/disks/{disk}/git/info/refs	service=git-upload-pack or git-receive-pack	Git ref advertisement.
POST	/v1/disks/{disk}/git/git-upload-pack	Git request body	Git fetch negotiation and pack.
POST	/v1/disks/{disk}/git/git-receive-pack	Git request body	Git push status after durable publication.

These endpoints use smart HTTP protocol v0. Authentication uses the same Bearer header as the other disk APIs.

Constraints and errors

This experimental adapter reconstructs a disposable bare repository for every HTTP request. Its CPU and scratch-disk costs grow with retained committed history. It is intended for compatibility tests and storage comparisons; transport caching has not been implemented.

Only SHA-1 repositories and branch refs are supported. Tags, submodules, ref deletion and shallow imports are unsupported. Private staging branches are excluded from advertised refs and cannot be pushed. Paths must satisfy the filesystem’s UTF-8, name and length limits. Git import preserves identity for unchanged paths; Git rename detection does not preserve wabe Disk object IDs yet. Imported messages retain their original bytes in Git; the filesystem commit listing shows at most 8192 bytes of UTF-8 text.

Non-fast-forward updates support git push --force-with-lease. Receive-pack checks the expected Git ID; publication also rejects a native branch change since the request began. An active merge/rebase rejects incoming updates. The Git protocol cannot distinguish --force from --force-with-lease; use the latter for client-side stale-lease protection. See branch-local Git commands.

401 means authentication failed; 400 means unsupported refs, paths or modes; 409 means a changed or dirty target branch; 500 means Git, storage or corruption failure. Git can also return per-ref rejection inside a successful HTTP response. A missing acknowledgement leaves the push outcome uncertain; fetch refs before retrying. Git pushes currently do not emit file notification events.

A commit retained as another commit’s parent cannot be deleted. Linear rebase creates new commits and preserves old retained records; it does not delete or squash the old stored history.

Imported file metadata can contain an internal branch_id absent from the branch list. Each imported commit uses its own version lookup prefix. CommitInfo.branch_id identifies the public owning branch. This mapping is experimental.