Quickstart

Create or clone a repo, make a change, publish a branch, and merge it.

Markdown

All pages

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 --import-git inside an existing Git checkout. Git import and export covers the details.

Working against a huge repo? oak clone acme/web --shallow leaves out the history, and --path checks out only the directories you need. See Sparse clones.

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. Start a task#

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

This creates a branch from the latest main named after the summary, sets the summary as its description, and pushes it.

In a repo you created with oak init, oak start skips the push until step 5 links it to the server.

3. 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 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.

4. Describe the change#

oak start set the description to your summary. Refine it once you know what the branch really does:

oak desc "Add a dark-mode toggle to the settings page, stored per account"

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.

5. Publish the branch#

If you cloned the repo, publish your commits:

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.

6. Merge it#

When the change is ready, merge it:

oak merge           # squash the branch onto main

If main has moved since you started, run oak pull first.

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 merging main in hits a conflict, Merging and conflicts walks through it.

7. Start the next task#

oak start "Fix the login redirect"

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

Where next#

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