> ## Documentation Index
> Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Branch-aware editing

> How Oxygen handles protected branches and feature-branch forks in the IDE

Workspaces that import from GitHub use a branch-aware editing flow.
You serve from one branch (typically the deployed one) and Oxygen
automatically creates a feature branch when an editor would otherwise
write to a protected branch.

Two settings on every workspace control the behaviour:

* **`protected_branches`** — list of branches where saving a file
  triggers Oxygen to create a feature branch instead of overwriting the
  current branch.
* **`base_branch`** — the branch new feature branches fork from. When
  unset, they fork from whatever the workspace currently has checked
  out.

These live in your workspace's `config.yml` and are editable from the
IDE (or from **Manage → Workspaces → Branches**).

## `protected_branches`

<ParamField path="protected_branches" type="string[]" default="[default_branch]">
  Branches where saving a file in the IDE auto-creates a feature branch
  instead of overwriting the current branch. Defaults to the
  repository's default branch (usually `main`).
</ParamField>

When the IDE is viewing a file on a protected branch, the **Save**
button becomes **Save to new branch** and shows a *"Saving will create
a new branch"* hint. Pressing save creates a worktree at
`<user-slug>/<timestamp>` (e.g. `alice/2026-04-15-113742`), writes the
file there, and switches the IDE to that branch.

```yaml config.yml theme={null}
protected_branches:
  - main
  - develop
```

## `base_branch`

<ParamField path="base_branch" type="string">
  Branch used as the fork point when Oxygen auto-creates a feature
  branch. When unset, new branches fork from whatever the workspace
  currently has checked out.
</ParamField>

If your workspace serves from a dedicated deployment branch, you
usually want new work to fork from a different integration branch.
`base_branch` is the switch:

```yaml config.yml theme={null}
# Workspace serves from `deploy` (protected). New feature branches
# fork from `main` so they start from the latest integration work,
# not from whatever has been deployed.
protected_branches:
  - deploy
base_branch: main
```

`base_branch` only affects **newly created** branches. Switching to a
branch that already exists always uses that branch's existing ref as
the starting point.

### When to use it

Use `base_branch` when your workflow has a clear split between:

* **A deployment / serving branch** — the one Oxygen runs against.
* **An integration branch** — the one humans merge PRs into and where
  new work should start.

If your repository has only one long-lived branch, leave `base_branch`
unset.

## Full example

```yaml config.yml theme={null}
databases:
  - name: warehouse
    type: postgres
    ...

models:
  - name: openai-4o-mini
    vendor: openai
    model_ref: gpt-4o-mini

defaults:
  database: warehouse

protected_branches:
  - deploy
base_branch: main
```