Quickstart

This page takes you from nothing to a change merged on main. It assumes you've installed the CLI and signed in.

1. Get a repository#

Pick whichever matches where your code is now.

Start a new repo:

oak init my-app
cd my-app

Clone one that's already on Oak:

oak clone acme/web      # or just `oak clone` to pick from a list
cd web

Bring a Git repo over:

oak clone https://github.com/acme/web.git     # fetches with git, replays history into Oak
cd web

…or run oak init inside an existing Git checkout and accept the import prompt. Git import, export, and interop covers the details, including importing from GitHub in the browser with nothing installed.

Working against a huge repo? Skip the clone and mount it instead — you're editing in seconds.

Whichever way you came in, you're now on a personal branch — something like zdgeier-3f2a8b — parented onto main. You never work on main directly; see Branches and descriptions.

2. Make a change and checkpoint it#

Edit some files, then:

oak status          # what changed
oak diff            # the changes themselves (full-screen viewer on a terminal)
oak commit          # save a local checkpoint

oak commit takes no message, on purpose. Commit as often as you like — every checkpoint gets folded into one commit when the branch merges.

3. Describe the change#

oak desc "Add a dark-mode toggle to the settings page"

The branch description is the commit message for the whole branch. It becomes the message of the single commit that lands on main when you merge, so write it for someone reading main's history later.

4. Publish the branch#

If you cloned the repo, it's already linked to the server:

oak push

If you created it with oak init (or imported from Git), the first push also creates the repo on oak.space, so Oak needs to know which organization owns it. On an interactive terminal, plain oak push asks you to pick one. In a script or an agent run, there's no terminal to ask, so name it:

oak push --repo acme/my-app

acme must be an existing organization you can publish to — every account has a personal one named after its username. The repo itself is created if it doesn't exist. After this first link, plain oak push works.

Agents: never guess the owner. If you don't know which organization to publish into, ask. OAK_REPO=acme/my-app works in place of the flag.

Your branch now shows up on the repo's Branches page at https://oak.space/acme/my-app/branches. Open it in a browser with oak open.

5. Merge it#

When the change is ready, bring in anything that's landed on main since you started, then merge:

oak pull            # merge the latest main into your branch
oak merge           # squash the branch onto main

Or click Merge on the branch's page in the web UI. Either way, main gains exactly one commit whose message is your branch description, and the branch is closed.

If the repo has CI, the merge waits for it to pass — oak merge --wait rides it out for you. If oak pull hits a conflict, Merging and conflicts walks through resolving it.

6. Start the next task#

oak switch -c       # new branch off the latest main, with a generated name
oak switch -c fix-login-redirect   # …or name it yourself

That's the whole loop: branch → edit → commit → describe → push → merge.

Where next#

• Coming from Git — command-by-command translation.
• Making changes — ignore files, hooks, undoing things.
• Working with agents — set up Claude Code, Codex, or Cursor to follow this loop on its own.
• Continuous integration — add a workflow file and gate merges on it.