<Worktree>

Execute a subtree in a separate JJ worktree rooted at path.

Import

import { Worktree, Task, Parallel, MergeQueue } from "smithers-orchestrator";

Props

Prop	Type	Default	Description
id	string	auto-generated	Stable id for tracking/deduping.
path	string	—	Filesystem path for the JJ workspace root. Required; non-empty.
branch	string	undefined	Branch to check out. Omit to use the current branch.
baseBranch	string	"main"	Base branch/revision for sync or creation.
skipIf	boolean	false	Skip the subtree.
children	ReactNode	—	Nested tasks and control-flow nodes.

Basics

<Worktree path="/tmp/smithers/wt-a">
  <Task id="build" output={outputs.outputC}>{{ value: 1 }}</Task>
  <Task id="test" output={outputs.outputC}>{{ value: 2 }}</Task>
  <MergeQueue>
    <Task id="apply" output={outputs.outputC}>{{ value: 3 }}</Task>
  </MergeQueue>
  <Parallel maxConcurrency={2}>
    <Task id="lint" output={outputs.outputC}>{{ value: 4 }}</Task>
  </Parallel>
  <Task id="package" output={outputs.outputC}>{{ value: 5 }}</Task>
  <Task id="release" output={outputs.outputC}>{{ value: 6 }}</Task>
</Worktree>

Descendant tasks receive worktreeId and a normalized absolute worktreePath in their descriptors. The engine uses worktreePath as cwd for JJ operations and tool execution.

Path Resolution

Input	Behavior
Relative path	Resolves against baseRootDir (or process.cwd()).
Absolute path	Preserved and normalized.
Empty/whitespace	Rejected: <Worktree> requires a non-empty path prop.

Nesting

Innermost <Worktree> in scope determines a task’s effective worktreeId/worktreePath.

<Worktree id="outer" path="/tmp/wt-outer">
  <Task id="a" output={outputs.outputC}>{{ value: "outer" }}</Task>
  <Worktree id="inner" path="./nested">
    <Task id="b" output={outputs.outputC}>{{ value: "inner" }}</Task>
  </Worktree>
</Worktree>

With Parallel and MergeQueue

<Worktree path="/tmp/wt-queue">
  <MergeQueue>
    {prs.map((pr) => (
      <Task key={pr.id} id={`apply-${pr.id}`} output={outputs.outputC}>
        {{ value: pr.id }}
      </Task>
    ))}
  </MergeQueue>
</Worktree>

Internals

• Renders to <smithers:worktree>.
• Extraction assigns worktreeId and worktreePath to every descendant task descriptor.
• The scheduler is unaware of worktrees; the engine consumes these fields to scope JJ operations and reverts.

Notes

• Duplicate id values are rejected.
• Use baseBranch to create/rebase from something other than main.
• Prefer absolute ephemeral paths in CI; relative paths for local portability.