Skip to main content
The Git section controls how Radius creates and retires worktrees for a project.

​
Choose the starting ref

git.base_ref is the Git ref used when Radius creates a new worktree.
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.
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.
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:
Radius does not delete the configured base branch. A failed archive command blocks worktree removal and leaves the branch available for recovery.
This setting deletes the local branch only. It does not delete a branch from GitHub or another remote.

​
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 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.