Create worktrees

Parse $ARGUMENTS as the number of worktree slots to create. Default to 1 if empty or not a positive integer. Must be 1-4.

N=${ARGUMENTS:-1}
# Validate: must be 1, 2, 3, or 4. Abort if anything else.

Abort if not in a git repo. Abort if working directory is dirty (git status --porcelain is non-empty).

REPO_ROOT=$(git rev-parse --show-toplevel)
REPO_NAME=$(basename "$REPO_ROOT")

Detect layout

Walk up from $REPO_ROOT (max 3 levels) checking each ancestor for build system markers:

Nested ROS2: an ancestor has install/setup.bash AND the repo is inside that ancestor's src/ directory.

Nested Cargo: an ancestor contains Cargo.toml with [workspace] in it.

Nested CMake: an ancestor contains CMakeLists.txt that is NOT the repo's own (i.e., a parent project).

Standalone: no build system markers found above the repo.

Confirm with user

Present the detected layout via AskUserQuestion before proceeding:

Detected standalone / nested ROS2 / nested (Cargo workspace) / nested (CMake superproject) layout.

• Flow A (standalone): bare repo + internal worktrees inside $REPO_ROOT/
• Flow B (nested ROS2): overlay worktrees outside workspace at $WT_BASE/
• Flow C (nested): flat worktrees outside at $WT_BASE/

Options: [Proceed with detected layout] / [Switch to standalone] / [Switch to nested] / [Abort]

This protects against misdetection before any destructive operations.

---

Flow A: Standalone repo (bare repo + internal worktrees)

Use for: standalone Python, Rust, C, C++, Go, Node, etc.

Abort if .bare/ already exists (already set up).

Convert to bare repo

Convert in-place (preserves all local branches, unpushed commits, stashes, hooks):

1. mv $REPO_ROOT/.git $REPO_ROOT/.bare
2. echo "gitdir: ./.bare" > $REPO_ROOT/.git
3. git --git-dir=$REPO_ROOT/.bare config core.bare true
4. git --git-dir=$REPO_ROOT/.bare config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"

Remove the old working tree files — everything in $REPO_ROOT except .bare/ and .git:

cd "$REPO_ROOT"
ls -A | grep -v '^\.\(bare\|git\)$' | xargs rm -rf

Create worktrees

git worktree add main main
for i in $(seq 1 $N); do
  git worktree add "w$i" -b "w$i-slot" main
  git push -u origin "w$i-slot"
done

Install dependencies

For each worktree (main, w1 .. w$N), cd in and detect build system (see dependency table below).

Confirm

Print the tree showing only the slots that were created:

$REPO_NAME/
├── .bare/
├── main/   ← read-only reference (always on main)
├── w1/     ← work slot
└── ...     ← up to w$N

Remind user: cd w1 && git checkout -b feature-name to start working.

---

Flow B: Nested ROS2 repo (external overlay worktrees)

Use for: ROS2 package inside ros2_ws/src/<pkg>/

The original repo stays in place as the "main" (read-only reference). Worktrees go outside the workspace to avoid colcon conflicts.

Determine paths

PKG_NAME="$REPO_NAME"
SRC_DIR=$(dirname "$REPO_ROOT")          # ros2_ws/src/
WS_DIR=$(dirname "$SRC_DIR")             # ros2_ws/
WS_PARENT=$(dirname "$WS_DIR")           # parent of ros2_ws
WT_BASE="$WS_PARENT/${PKG_NAME}-worktrees"
SETUP_FILE="$WS_DIR/install/setup.bash"

Abort if worktrees directory already has w1/ (already set up).

Create overlay worktree slots

For each slot w1 .. w$N:

for i in $(seq 1 $N); do
  mkdir -p "$WT_BASE/w$i/src"
  git worktree add "$WT_BASE/w$i/src/$PKG_NAME" -b "w$i-slot" main
  git push -u origin "w$i-slot"
done

Build each slot

For each slot w1 .. w$N:

source "$SETUP_FILE"
cd "$WT_BASE/w$i"
colcon build --symlink-install

Confirm

Print the tree showing only the slots that were created:

$WS_DIR/                                      ← parent workspace (underlay)
└── src/
    └── $PKG_NAME/                            ← original repo = "main"

$WT_BASE/                                     ← outside workspace
├── w1/
│   ├── src/$PKG_NAME/                        ← git worktree
│   ├── build/
│   └── install/
└── ...                                       ← up to w$N

Remind user: cd $WT_BASE/w1/src/$PKG_NAME && git checkout -b feature-name to start working.

Print rebuild command: cd $WT_BASE/w1 && source $SETUP_FILE && colcon build --packages-select $PKG_NAME

---

Flow C: Nested general repo (external flat worktrees)

Use for: Cargo workspace member, CMake subproject, etc.

The original repo stays in place as "main". Worktrees go outside as siblings next to the parent project.

Determine paths

PARENT_PROJECT = the ancestor directory where the build system marker was found during detection.

WT_BASE="$(dirname "$PARENT_PROJECT")/${REPO_NAME}-worktrees"

Abort if worktrees directory already has w1/ (already set up).

Create worktree slots

mkdir -p "$WT_BASE"
for i in $(seq 1 $N); do
  git worktree add "$WT_BASE/w$i" -b "w$i-slot" main
  git push -u origin "w$i-slot"
done

Install dependencies

For each slot w1 .. w$N, cd in and detect build system (see dependency table below).

Confirm

Print the tree showing only the slots that were created:

$PARENT_PROJECT/                              ← parent workspace/superproject
└── .../$REPO_NAME/                           ← original repo = "main"

$WT_BASE/                                     ← outside parent project
├── w1/     ← work slot
└── ...     ← up to w$N

Remind user: cd $WT_BASE/w1 && git checkout -b feature-name to start working.

Note: these flat worktrees build standalone, outside the parent workspace. If the project depends on workspace siblings, the user may need to configure build paths manually.

---

Shared steps (all flows)

Initialize submodules (if any)

If .gitmodules exists in any worktree, run git submodule update --init --recursive in each.

Import vcstool repos (if any)

If any *.repos file exists, run vcs import src < <file>.repos in each worktree.

Dependency table

For each worktree, detect build system by checking which files exist, in this order (first match wins):

Check	Run
uv.lock	uv sync
poetry.lock	poetry install
Pipfile.lock	pipenv install
requirements.txt	pip install -r requirements.txt
Cargo.lock or Cargo.toml	cargo build
src/*/package.xml (ROS2 workspace)	colcon build
CMakeLists.txt	cmake -B build && cmake --build build
meson.build	meson setup build && meson compile -C build
Makefile	make
pnpm-lock.yaml	pnpm install
package-lock.json	npm install
yarn.lock	yarn install
go.sum	go mod download
Gemfile.lock	bundle install

If none match, skip — tell the user no build system was detected.

Note: for Flow B (nested ROS2), dependency installation is handled by colcon build in the overlay — skip this table.