Coming from Git

How Git's concepts and commands map onto Oak, and what's deliberately different.

Markdown

All pages

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#

Command mapping#

GitOakNotes
git initoak 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 1oak clone --shallow
git sparse-checkoutoak clone --path <dir>, oak sparseSee Sparse clones.
git worktree addoak worktree add <dir>A second checkout on a new branch off main. oak start "…" --worktree starts a task in one.
git statusoak status--short/--porcelain are Git-compatible.
git diffoak diffOpens a full-screen viewer on a terminal; --print for plain output.
git diff main...featureoak diff featureShows 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 pushoak pushPublishes the current branch. Pushes to main are refused.
git pull / git pull --rebaseoak pullAlways merges main into your branch.
git fetchoak fetchRefreshes 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 branchoak branch / oak branch list--remote reads the server.
git branch --show-currentoak branch --show-current
git branch -d <b>oak close <b>Closed branches can be reopened from the web.
git merge / "Squash and merge"oak mergeServer-side squash onto main.
git rebase -ioak splitReorder, drop, or split a branch's commits into separate branches.
git restore <path>oak restore <path>-s <commit> to restore from elsewhere.
git reset --hardoak resetDiscards uncommitted changes.
git logoak log-S / -G pickaxe search work as in Git.
git rev-parse HEADoak hash
git archiveoak export --tree-onlyWrites one commit's files to a directory.
.gitignore.oakignoreSame syntax. Oak falls back to .gitignore when there's no .oakignore.
.git/hooks/pre-commit.oak/hooks/pre-commitLocal only, like Git.
GitHub ActionsYour own CI, plus marks (oak mark)Oak runs no checks. Your tests record what passed by moving a mark, and deploy machines follow one.
CODEOWNERSPath rulesSet 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)#

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.

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