> ## 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 the background, when configured. The command can
   prepare the checkout and arrange the Radius group without opening a terminal.

Worktree settings continue to resolve from the source project, including local
overrides and secrets. See [Run and archive scripts](/docs/project-settings/run-and-archive-scripts)
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.