# Quickstart

This page takes you from nothing to a change merged on `main`. It assumes you've [installed the CLI and signed in](/docs/install).

## 1. Get a repository

Pick whichever matches where your code is now.

**Start a new repo:**

```bash
oak init my-app
cd my-app
```

**Clone one that's already on Oak:**

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

**Bring a Git repo over:**

```bash
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](/docs/git) covers the details, including importing from GitHub in the browser with nothing installed.

**Working against a huge repo?** Skip the clone and [mount](/docs/mounts) 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](/docs/branches).

## 2. Make a change and checkpoint it

Edit some files, then:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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](/docs/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](/docs/merging) walks through resolving it.

## 6. Start the next task

```bash
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](/docs/coming-from-git) — command-by-command translation.
- [Making changes](/docs/making-changes) — ignore files, hooks, undoing things.
- [Working with agents](/docs/agents) — set up Claude Code, Codex, or Cursor to follow this loop on its own.
- [Continuous integration](/docs/ci) — add a workflow file and gate merges on it.