Git import and export

Bring a Git repo into Oak, and get your history back out as Git.

Markdown

All pages

Code moves between Git and Oak two ways: import a Git history into Oak, and export an Oak history back to Git. Both run in the oak CLI on your machine and need git on your PATH.

You want to…Use
Bring a Git repo over from its URLoak clone <git-url>
Convert a Git checkout you already haveoak init --import-git
Bring over a large repository without a local Oak copyoak import
Start a repo from a folder in the browserUpload a folder
Get the history back out as Gitoak export

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 (your Git credentials apply), creates an Oak repo, replays the history onto main, and leaves you on a personal branch at the tip. It then offers to delete the now-redundant .git directory, and keeps it if you decline or there's no terminal to ask. If the import fails, the destination is removed so you can run the command again.

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 --import-git

Oak replays the Git history onto main and puts you on a personal branch at the tip. Your files are left exactly as they are: anything that differs from the last Git commit, like uncommitted changes, untracked files, or line endings Git converted on checkout, shows up in oak status. Your .git directory is untouched, so you can keep using Git alongside for a while; on a terminal Oak offers to remove it.

The one exception is files Git never checked out, as in a git clone --no-checkout or the folders a sparse checkout leaves out. Oak writes those from the last commit, so they don't show as deleted. A file you deleted yourself stays deleted.

On a terminal, plain oak init asks whether to import. Without one (scripts, agents, --json) it refuses until you choose: --import-git to import, or --no-import-git to start an empty repository beside the Git history. With --json, the receipt's git_import field lists what was imported and anything left out.

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 with the imported history on main:

oak push --repo acme/web

oak push --plan --json --repo acme/web shows what that first push would send, without sending anything. A history too large for one push is refused before anything is sent, with a pointer to oak import.

Then start working; see the Quickstart.

Import a large repository#

oak import ~/src/linux --repo acme/linux

oak import reads a Git repository's history and publishes it straight to a new repository on the server, without converting it into a local Oak repo first. It works through the history a window at a time (about 1,000 commits or 1 GB of new file content). For each window it uploads the new files, then moves the new repository's main forward, then drops its local copy of those files. Disk use stays around one window, however large the history.

When it's done, get a checkout with oak clone acme/linux --shallow. The same things are kept and left out as with the other imports, listed below.

What's preserved#

Kept:

Left out, and listed when it happens:

Not imported:

oak clone <git-url> refuses a repository whose checkout puts files under .oak/hooks (or anything else under .oak/ besides what Oak tracks), because Oak runs .oak/hooks on commit.

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 form 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 writes an Oak branch's history (by default the current one) into a new Git repository and checks it out. Push it anywhere. This is Oak's escape hatch: your code and its history are never trapped.

FlagEffect
-b, --branchThe Oak branch to export (default: current).
--git-branchName of the branch in the Git repo (default: same as the Oak branch).
-f, --forceWrite into a destination that isn't empty. In an existing Git repo this overwrites the branch and leaves the working tree alone.
--tree-only --at <commit>Write just one commit's files, without history or Git.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].