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

# Git and worktrees

> Configure the starting ref, remote, push behavior, and archive lifecycle for Radius worktrees.

The Git section controls how Radius creates and retires worktrees for a project.

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[git]
base_ref = "origin/main"
remote = "origin"
delete_branch_on_archive = false
push_auto_setup_remote = true
```

## Choose the starting ref

`git.base_ref` is the Git ref used when Radius creates a new worktree.

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[git]
base_ref = "origin/main"
```

Leave it empty or omit it to let Radius choose in this order:

1. The symbolic default branch for the configured remote
2. `<remote>/main`
3. `<remote>/master`
4. `HEAD`

Radius verifies the ref before allocating the worktree. A repository without an
initial commit must receive its first commit before Radius can create a worktree.

## Configure the remote

`git.remote` defaults to `origin`. Radius uses it as the repository's default push
remote and when resolving an automatic starting ref.

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[git]
remote = "upstream"
```

Repositories without that remote can still create local worktrees. The setting
takes effect after the remote exists.

## Set an upstream on first push

When `git.push_auto_setup_remote` is `true`, a plain `git push` from a new
worktree records its upstream branch automatically.

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[git]
push_auto_setup_remote = true
```

Disable it if your repository requires explicit upstream selection.

## Delete local branches after archive

Set `git.delete_branch_on_archive` to remove a worktree's local branch after its
archive command succeeds and Radius removes the worktree:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[git]
delete_branch_on_archive = true
```

Radius does not delete the configured base branch. A failed archive command blocks
worktree removal and leaves the branch available for recovery.

<Warning>
  This setting deletes the local branch only. It does not delete a branch from
  GitHub or another remote.
</Warning>

## Worktree creation lifecycle

When you create a worktree, Radius:

1. Resolves and verifies the configured starting ref.
2. Creates an isolated Git worktree.
3. Copies the configured ignored files.
4. Opens the worktree as a project group.
5. Runs the setup command in its visible terminal, when configured.
6. Runs the startup command for the new group, when configured.

Worktree settings continue to resolve from the source project, including local
overrides and secrets. See [Scripts and automation](/docs/project-settings/scripts-and-automation)
for the command lifecycle.

## Archive lifecycle

Before removing a worktree, Radius stops its project terminals and runs the
configured archive command. If the command succeeds, Radius removes the worktree
and applies the branch-deletion preference.

Session worktrees can also be restored from Radius's worktree history with their
captured staged, unstaged, and untracked changes.