Git import, export, and interop

Oak is designed to be easy to arrive at and easy to leave. This page covers every way code moves between Git and Oak.

Import from GitHub on the web#

No CLI, no Git — oak.space clones and converts the repo on its servers.

1. Connect GitHub, once: under Settings → GitHub, choose Connect GitHub and install Oak's GitHub App on the repositories you want (all, or a selection). For importing, Oak asks only for read access and mints a short-lived, single-repo token for each import.
2. Pick a repo: the Import from GitHub panel on your dashboard lists the repositories your connection can see.
3. Choose what to bring: the branch to import and the destination organization; optionally a different name, public visibility, and collaborators to invite. Oak checks the name is free as you type.
4. Import: a progress page streams status and opens the new Oak repo when it's done.

The web importer brings the one branch you choose straight onto the server as main — there's nothing to push afterwards. Run oak clone <org>/<repo> (or mount it) to get a working copy.

Import with oak clone#

oak clone https://github.com/acme/web.git
oak clone [email protected]:acme/web.git
oak clone https://git.example.com/acme/web.git my-dir    # choose the directory

Oak runs your system git clone (so git must be on your PATH, and your Git credentials apply), creates an Oak repo, replays every commit onto main, and leaves you on a personal branch at the tip. It then offers to delete the now-redundant .git directory — keeping it if you decline or there's no terminal to ask.

What counts as a Git URL: anything starting with git@, ssh://, or git://; anything ending in .git; and github.com, gitlab.com, and bitbucket.org URLs. For a self-hosted server over HTTPS, make sure the URL ends in .git so Oak doesn't read it as an Oak org/repo.

Oak-only flags (--branch, --path, --detached, --from, --json) are rejected with a Git URL — the importer always brings the checked-out history.

Convert a checkout in place#

cd my-existing-git-repo
oak init
# Detected an existing git repository here. Import its history into oak?

Accept, and Oak replays the Git history onto main, puts you on a personal branch at the tip, and offers to remove .git. Decline, and your .git is untouched — handy if you want to keep using Git alongside for a while. (The prompt needs a terminal.)

Publish what you imported#

A CLI import lives on your machine until you push. The first push names the owner, which creates the repo on oak.space:

oak push --repo acme/web

Then merge your branch, or start working — see the Quickstart.

What's preserved#

Kept:

• The full commit graph in order, including both parents of merge commits.
• Every commit's original author, email, message, and timestamp.
• File modes: regular, executable, and symlinks.

Dropped or simplified:

• Submodules are skipped — Oak has no submodule concept.
• Octopus merges (three or more parents) keep their first two parents.
• Only one line of history comes across: the checked-out HEAD for CLI imports, or the branch you pick on the web. Other branches and tags aren't recreated.

Your first oak status after importing is clean: Oak rewrites the working tree from its own records, so .gitattributes smudge filters and leftover submodule directories don't show up as changes. Your .gitignore keeps working — Oak reads it when there's no .oakignore.

Upload a folder#

When creating a repo on oak.space, you can upload a folder from your computer instead of starting empty. The import dialog has presets for Godot, Unity, and Unreal projects that skip their generated directories. Files can also be uploaded into an existing repo from its page.

Export back to Git#

oak export ../web-as-git
oak export ../web-as-git --branch main --git-branch main

oak export replays an Oak branch's history (by default the current one) into a brand-new Git repository, preserving each commit's author, email, and timestamp. Push it anywhere. This is Oak's documented escape hatch: your code and its history are never trapped.

Clone an Oak repo with Git#

git clone https://oak.space/acme/web.git

Every Oak repo can be cloned by stock Git — and anything built on it, like package managers, deploy scripts, or Claude Code's /plugin marketplace add — as a read-only snapshot of main:

• It's a single commit containing main's current files, with no history. Use oak export for history.
• It's fetch-only; git push to it fails.
• It works for public repos, and for the @public paths of a private repo. The endpoint doesn't accept API keys or passwords yet, so a private repo answers "not found" to git — use oak clone or oak export for those.
• Path permissions apply: restricted files are left out, and for outsiders only @public paths are included.

Mirror to GitHub#

A repo can keep a copy of main on GitHub — as a backup, or to run GitHub Actions or other GitHub-side tooling. Set it up under the repo's Settings → Export:

1. Create an empty repo on GitHub, and make sure Oak's GitHub App (or your connected GitHub account) can push to it.
2. Choose it, and the branch to mirror to.

On every merge to main (and whenever you click Sync now), Oak writes main's current files to that GitHub branch as a single snapshot commit and force-pushes it. Like the Git clone endpoint, it's the current state, not a history replay. Because it force-pushes, use a repo or branch dedicated to the mirror; Oak refuses to overwrite a branch whose latest commit it didn't create. Files over 100 MB can't be mirrored (GitHub's limit), and restricted paths are left out.