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 URL | oak clone <git-url> |
| Convert a Git checkout you already have | oak init --import-git |
| Bring over a large repository without a local Oak copy | oak import |
| Start a repo from a folder in the browser | Upload a folder |
| Get the history back out as Git | oak 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.
- ORG/REPO is created if it doesn't exist, and must not have history of its own.
- If the import stops, run the same command again. It resumes where
mainstopped. - Progress goes to stderr, one line per window. With
--json, stdout gets one receipt at the end. --scratch DIRchooses where the working files and resume state go (default: under your cache directory). They're removed when the import finishes.--window-commits Nand--window-mb Nsize the windows.--dry-runconverts the whole history and reports what would be uploaded, and how long each phase took, without contacting the server.
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:
- The commit graph in order, including both parents of merge commits.
- Every commit's author, email, message, and committer timestamp.
- File modes: regular, executable, and symlinks.
Left out, and listed when it happens:
- Submodules. Oak has no submodule concept.
- Paths Oak can't track: names that aren't valid UTF-8 or that hold control characters, any
.gitor.oakrootpath component, and anything under.oak/other than.oak/attributes. They're dropped from every commit. - Octopus merges (three or more parents) keep their first two parents.
- History before a shallow clone's cut-off. A shallow Git clone imports from its oldest fetched commits.
Not imported:
- Only one line of history comes across: the checked-out
HEAD. Other branches aren't recreated. - Tags. Oak has no tags; refer to commits by hash.
- Git LFS content. Files tracked by LFS come across as their pointer files.
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.
- Every commit on the branch comes across with its author, message, and timestamp, so exporting the same history twice gives the same Git commit ids. A history imported from Git exports back to the commits it came from.
- Merges within the branch keep both parents. A squash-merge on
mainexports as one commit, the way it reads on Oak. - Every tracked file is written as Oak stores it. Your
.gitignore,.gitattributes, hooks, and signing settings don't change what's exported. - A checkpoint with no message gets
oak: <hash>as its Git message. - From a shallow clone, the Git history starts at the oldest commit the clone has. Export from a full clone for all of it. A sparse clone needs the left-out directories first (
oak sparse add).
| Flag | Effect |
|---|---|
-b, --branch | The Oak branch to export (default: current). |
--git-branch | Name of the branch in the Git repo (default: same as the Oak branch). |
-f, --force | Write 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. |