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. - 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 | --import-git brings over 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 worktree add <dir> | A second checkout on a new branch off main. oak start "…" --worktree starts a task in one. |
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. To begin a task, use oak start "<summary>", which also describes and pushes the branch (Starting a task). |
git checkout <sha> | oak switch -d <sha> | Detached HEAD. A unique prefix of 4+ characters works. |
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 | |
git archive | oak export --tree-only | Writes one commit's files to a directory. |
.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 | Your own CI, plus marks (oak mark) | Oak runs no checks. Your tests record what passed by moving a mark, and deploy machines follow one. |
CODEOWNERS | Path rules | Set per folder or file in the repo's Settings → Access: who owns, reads, writes and approves it. See Path rules. |
Things Git has that Oak doesn't (yet)#
- 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 with an Oak repo#
Oak doesn't serve repos to Git. When a tool needs a Git repository, oak export writes one, with the history, into a separate directory. See Git import and export.
Inside an Oak checkout, don't run
git. An Oak repo has a.oak/directory and no.git.