Branches and worktrees

Run branch commands from anywhere inside the target Git repository.

Open an existing branch

shirei branch feature/my-change

If the branch exists only as a remote branch such as origin/feature/my-change, Shirei creates a local tracking branch in a linked worktree.

Create a branch

shirei branch feature/my-change --base main

Supplying both name and base avoids the branch and base pickers. If the branch already exists, Shirei ignores --base with a warning.

Without a name, shirei branch opens a picker over local and remote branches. A new named branch without --base opens a second picker for its starting ref.

Side effects

A successful branch command can:

Create a local branch and linked Git worktree.
Create directories below worktree_root.
Update Shirei’s worktree and recent-directory state.
Create or reuse a tmux session or Herdr workspace.
Run repository setup commands for a newly created worktree.

New worktrees use:

<worktree_root>/<sanitized-repository>/<sanitized-branch>

Characters outside ASCII letters, digits, -, and _ become - in session and path names.

Automatic setup

When run_install_on_create = true, Shirei starts an install tmux window or unfocused Herdr tab and runs the first match:

Makefile with an install: target → make install.
package.json → a lockfile-selected package manager install.
Cargo.toml → cargo build.

Lockfile	Command
`bun.lockb` or `bun.lock`	`bun install`
`pnpm-lock.yaml`	`pnpm install`
`yarn.lock`	`yarn install`
`package-lock.json` or none	`npm install`

Registry commands

# List saved entries
shirei worktrees

# Discover linked worktrees again
shirei worktrees scan

A leading ! in the list means the saved path is missing. Listing reads Shirei state and does not reconcile Git.

scan discovers repositories from configured roots and known entries, reads git worktree list --porcelain, and replaces the saved registry. Back up state first when registry continuity matters; a repository inspection failure can remove its old entries from the rebuilt result.

Continue with unfinished work and pruning.