# Roots

A root is a separate timeline inside one repository, with its own history and head. It has no branches and no CI. A root starts empty, or at a commit on `main`, which is how you keep a release line that takes patches apart from `main`.

Roots are behind a per-repository server flag. On a server or repository where it is off, `oak root` commands fail with the server's message (a root you can't see answers like one that doesn't exist). The flag is set by Oak server administrators, not by organization owners; ask us (see [Contributors](/docs/contributors)) if you need it on. Nothing in the CLI turns the flag on.

## Who can do what

- Everyone who can read the repository can read a root.
- A root's owner group and the organization's owners and admins can push to it. A root with no owner group is writable only by owners and admins.
- Owners and admins create roots; a group's maintainers can create roots that group owns. Maintainers of the owner group, and owners and admins, archive them.
- A root that started from `main` holds that commit's whole tree, including folders that [path rules](/docs/path-permissions) hide. Reading or starting one therefore takes being able to read every path of the repository. Someone who can't sees the root's metadata only and gets a 403 on pull.

## Create and list

```bash
oak root create notes                                   # an empty root
oak root create stable --from main --owner-group release  # start at main's head
oak root create hotfix --from FULL_64_CHAR_HASH         # start at an older commit on main
oak root create scratch --sync                          # a sync root instead of a direct one
oak root list [--archived] --json
oak root show stable --json
```

`--from` takes `main` or a full 64-character hash on `main`'s first-parent history; the server refuses anything else. `--owner-group GROUP` names the group that writes the root. Every `oak root` command takes `--repo OWNER/NAME` (default: the checkout's repository), `-r, --remote URL` and `--json`.

## Pull and push

```bash
oak root pull stable          # its files go to roots/stable/
# edit roots/stable/...
oak root push stable          # one commit on the root
```

The checkout ignores every directory a root was pulled into, so `roots/NAME/` is never committed to `main`. Inside a root directory, `pull` and `push` need no name; elsewhere they do. `--dir PATH` chooses a different directory.

`pull` merges per file. Files you didn't touch take the root's version, files only you changed are kept, and a file changed on both sides refuses the whole pull with exit 5 until you move your copy aside or pass `--force` to take the root's.

`push` sends only content the root doesn't already have. If the root moved since your last pull it exits 5: run `oak root pull`, then push again. A directory that was never pulled can't push to a root that already has commits.

## Archive

```bash
oak root archive stable --yes
```

An archived root's history stays readable and it takes no more pushes. `oak root list --archived` includes it.

See the [CLI reference](/docs/cli#oak-root) for every flag.