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) 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 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#

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#

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#

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 for every flag.