Oak will feel familiar — repos, branches, push, pull, diff — but a few of Git's defaults are deliberately turned around. This page is the translation table.
What's different, in short#
- No staging area.
oak commitsnapshots the whole working tree (or just the paths you name). There's noadd. - No commit messages. Commits are checkpoints. The branch carries the message, set with
oak desc, and it becomes the message of the squash commit onmain. - No local
main.mainlives on the server. Locally you're always on a feature branch;oak switch mainis an error, not a checkout. - One kind of merge. Merging a branch onto
mainalways squashes it to a single commit. There's no merge-commit or rebase option to choose between, and no pull-request object — the branch is the review unit. - Pull merges, never rebases.
oak pullmerges the latestmaininto your branch. History on your branch is never rewritten under you. - Clones are optional.
oak mountgives you a working tree backed by the server, with files fetched on first read. - Large files are normal files. Content is chunked and deduplicated (FastCDC + BLAKE3), so there's no LFS to set up.
Command mapping#
| Git | Oak | Notes |
|---|---|---|
git init | oak init | Also offers to import an existing .git history. |
git clone <url> | oak clone <org>/<repo> | A Git URL works too — it's imported. |
git clone --depth 1 | oak clone --shallow | |
git sparse-checkout | oak clone --path <dir>, oak sparse | See Sparse clones. |
git worktree add | oak mount <org>/<repo> <dir> | No clone behind each one. See Lazy mounts. |
git status | oak status | --short/--porcelain are Git-compatible. |
git diff | oak diff | Opens a full-screen viewer on a terminal; --print for plain output. |
git diff main...feature | oak diff feature | Shows what the branch contributes. |
git add -A && git commit -m … | oak commit | -m is refused. Describe the branch with oak desc. |
git commit --amend -m … | oak desc "…" | Change what the branch says it does. |
git push | oak push | Publishes the current branch. Pushes to main are refused. |
git pull / git pull --rebase | oak pull | Always merges main into your branch. |
git fetch | oak fetch | Refreshes your copy of main. |
git switch <b> / git checkout <b> | oak switch <b> | Fetches the branch if you don't have it. |
git switch -c <b> | oak switch -c [<b>] | Name is optional; one is generated. |
git checkout <sha> | oak checkout <sha> / oak switch -d <sha> | Detached HEAD. |
git branch | oak branch / oak branch list | --remote reads the server. |
git branch --show-current | oak branch --show-current | |
git branch -d <b> | oak close <b> | Closed branches can be reopened from the web. |
git merge / "Squash and merge" | oak merge | Server-side squash onto main. |
git rebase -i | oak split | Reorder, drop, or split a branch's commits into separate branches. |
git restore <path> | oak restore <path> | -s <commit> to restore from elsewhere. |
git reset --hard | oak reset | Discards uncommitted changes. |
git log | oak log | -S / -G pickaxe search work as in Git. |
git rev-parse HEAD | oak hash / oak rev-parse HEAD | |
git archive | oak archive | Zip of the working tree. |
.gitignore | .oakignore | Same syntax. Oak falls back to .gitignore when there's no .oakignore. |
.git/hooks/pre-commit | .oak/hooks/pre-commit | Local only, like Git. |
| GitHub Actions | .oak/workflows/*.yml | Native CI, GitHub-Actions-shaped but much smaller. |
CODEOWNERS | .oak/PERMISSIONS | Controls read access, not review. See Path permissions. |
Things Git has that Oak doesn't (yet)#
Being honest about the gaps:
- Tags. There's no tag object; refer to commits by hash.
- Issues, pull-request review threads, line comments. Review happens on the branch page and in the CLI (
oak branch review), not in comment threads. - Submodules. Imports skip them.
- Push to arbitrary remotes. You push to an Oak server. To leave,
oak exportwrites a complete Git repo you can push anywhere. - Branch rename.
oak branch renameis temporarily disabled.
Using Git tools against an Oak repo#
Stock git can clone any public Oak repo as a read-only snapshot of main:
git clone https://oak.space/acme/web.git
That's one commit with no history, meant for tooling (package managers, /plugin marketplace add, deploy scripts). For full history in Git form, use oak export. Both are covered in Git import, export, and interop.
Inside an Oak checkout, don't run
git. An Oak repo has a.oak/directory and no.git. If a tool insists on Git, export or snapshot-clone into a separate directory instead.