Skip to content
Arashi logoArashi

create Command

What It’s For

Section titled “What It’s For”

Start feature work across multiple repositories from a single command.

What It Does

Section titled “What It Does”
  • Creates a worktree for the target branch in each configured repository.
  • Ensures repositories are aligned to the same branch name.
  • In interactive mode, always creates the parent/meta worktree and prompts only for optional child repositories.
  • Reconciles managed ignore rules before creating any parent or child worktree.
  • Runs configured lifecycle hooks when present.

Usage

Section titled “Usage”
Terminal window
arashi create <branch> [options]

Key Options

Section titled “Key Options”
  • --only <repos> limit creation to comma-separated repository names.
  • --group <group> create worktrees only for repositories in the requested group. Repeat for multiple groups.
  • -i, --interactive pick repositories interactively.
  • --switch switch to the created parent worktree after create.
  • --no-switch disable configured create switch defaults for one invocation.
  • --launch open a terminal/editor context after create.
  • --no-launch disable configured create launch defaults for one invocation.
  • --sesh force sesh launch mode (implies launch behavior).
  • --conflict <strategy> preselect conflict handling (ABORT, REUSE_EXISTING).
  • --no-hooks disable hook execution.
  • --no-progress hide progress indicators.
  • --dry-run generate a plan without creating worktrees.
  • --move-changes move compatible uncommitted changes from the current workspace into the new worktree after create.
  • --json output machine-readable create results or structured unsupported-mode errors.

Examples

Section titled “Examples”
Terminal window
# Create branch worktrees across the workspace
arashi create feature-auth-refresh


# Create in specific repositories only
arashi create feature-auth-refresh --only api,web


# Create worktrees for the core repository group
arashi create feature-auth-refresh --group core


# Pick child repositories interactively while always creating the parent worktree
arashi create feature-auth-refresh --interactive


# Force launch for this run
arashi create feature-auth-refresh --launch


# Disable configured launch default for this run
arashi create feature-auth-refresh --no-launch


# Review the plan first
arashi create feature-auth-refresh --dry-run


# Create worktrees and emit JSON for automation
arashi create feature-auth-refresh --no-launch --no-switch --json


# Create worktrees and move current uncommitted work into them
arashi create feature-auth-refresh --move-changes

Notes

Section titled “Notes”
  • In standalone mode, create makes one worktree at the main root’s .worktrees/<branch> path from either the main or a linked worktree. Before any mutation, Git must report the exact destination as effectively ignored; repository/group filters and interactive multi-repository selection are rejected. See the Standalone Repository workflow.
  • create validates branch names and repository readiness.
  • On failure, coordinated operations can roll back to keep repos consistent.
  • Reconciliation honors existing effective tracked, repository-local, or global rules before using the clone’s stored scope or repository-local default. Scope none creates no ignore-file changes and warns for safe paths that remain unignored.
  • --dry-run previews managed ignore scope, effective sources, planned rules, warnings, and unsafe skips without changing ignore files or clone-local preference state.
  • If worktree creation is fully rolled back, reconciliation is restored too. If a worktree survives a partial failure, Arashi retains the ignore state needed for that final filesystem state and reports it.
  • Interactive create treats the parent/meta repository as the required anchor for the coordinated worktree; the selection prompt only controls child repositories.
  • --group targets configured semantic sets such as core, docs, extensions, agents, or infra.
  • When combined with --only, --group narrows the explicit repository list by intersection. Empty intersections fail before creating worktrees.
  • A partial coordinated worktree is valid. Add omitted child repositories later with arashi clone from inside that worktree.
  • Configure defaults in .arashi/config.json under defaults.create (switch, launch, launchMode).
  • When post-create launch runs inside a cmux-managed terminal, Arashi creates and focuses a cmux workspace rooted at the new primary worktree. This requires cmux v0.64.18 or newer and local socket access.
  • If cmux launch fails after worktree creation, the created worktrees remain available and Arashi reports the launch failure without falling back to standalone Ghostty.
  • An active tmux session nested inside cmux keeps the existing tmux/sesh launch behavior.
  • Precedence for launch/switch behavior is: explicit flag > opt-out flag > config default > built-in default.
  • JSON mode is intended for non-interactive automation. Launch modes that would open another app or session return a structured unsupported-mode error instead of mixing launch output with JSON.
  • JSON results include structured managed ignore details and final changed/restored state without mixing human reconciliation output into stdout.
  • When the source workspace has uncommitted changes, create output includes guidance for moving compatible changes with arashi move. In JSON mode, that guidance is returned as structured data instead of human text.

Agent Notes

Section titled “Agent Notes”
  • Check arashi status and arashi list before creating a branch so you do not duplicate an existing coordinated worktree.
  • Use --no-launch --no-switch for unattended agent runs unless the user explicitly wants an editor or shell session opened.
  • Prefer --json with explicit non-interactive flags when automation needs to verify created worktree paths.
  • Use --interactive when a task only needs some child repositories; the parent worktree is still present, so shared metadata and coordination remain available.
  • Prefer --group <group> over a long --only list when a known semantic group matches the task scope.
  • Treat managed ignore warnings as actionable workspace state; do not compensate by writing global Git configuration.
Section titled “Related Commands”