# Amdsmi Using Git Worktrees

> Use when starting amd-smi feature work, executing an implementation plan, or reviewing a PR that needs an isolated workspace away from the main checkout. Sets up a worktree following the rocm-systems-pr<PR#> convention.

- Skill: `rocm/amdsmi-using-git-worktrees` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add rocm/amdsmi-using-git-worktrees`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rocm/amdsmi-using-git-worktrees/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rocm (https://skillmd.com/u/rocm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rocm/amdsmi-using-git-worktrees

---


# Using Git Worktrees — amd-smi

Ensure work happens in an isolated workspace so the main checkout is never disturbed.

**Core principle:** Detect existing isolation first. Then use the project convention. Never fight the harness.

**Announce at start:** "I'm using the `amdsmi-using-git-worktrees` skill to set up an isolated workspace."

## amd-smi Worktree Convention

Worktrees of `rocm-systems` are created as **sibling directories** of the main
checkout. The prefix is always `rocm-systems-`, lowercase (never `amd-smi-…` or
uppercase `ROCM-…`). Pick the name by this tiered preference:

```
<parent>/rocm-systems-pr<PR#>                  # 1. preferred — a PR exists
<parent>/rocm-systems-<ticket#>                # 2. ticket work, no PR yet (e.g. rocm-systems-26211)
<parent>/rocm-systems-rocm-<ticket#>-<desc>    # 3. ticket + short desc when one name isn't enough
<parent>/rocm-systems-<branch-name>            # local feature branches with no ticket/PR
```

Derive the parent dynamically — do not hard-code it:

```bash
MAIN_CHECKOUT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")
```

Never create worktrees inside the main checkout (e.g., `./worktrees/`) for this repo — the convention is siblings.

## Step 0: Detect Existing Isolation

Before creating anything, check whether you're already in a linked worktree:

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
```

**Submodule guard** — `GIT_DIR != GIT_COMMON` is also true inside submodules. Verify:

```bash
git rev-parse --show-superproject-working-tree 2>/dev/null
```

If that returns a path → you're in a submodule, treat as a normal repo.

**If `GIT_DIR != GIT_COMMON` and not a submodule:** Already in an isolated worktree. Report path + branch. Skip to Step 3.

**If `GIT_DIR == GIT_COMMON`:** Normal checkout. Continue to Step 1.

## Step 1: Confirm Consent

If the user hasn't already asked for isolation in the current task:

> "Would you like me to set up an isolated worktree at `<parent>/rocm-systems-pr<PR#>`? It protects your current checkout from changes."

If declined → work in place, skip to Step 3.

## Step 2: Create the Worktree

For PR-based work:

```bash
PR_NUM=<number>
BRANCH=<branch-name>   # the PR's branch

# Derive parent from the current checkout
MAIN_CHECKOUT=$(git rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")
WORKTREE="${WORKTREE_PARENT}/rocm-systems-pr${PR_NUM}"

cd "$MAIN_CHECKOUT"

# Fetch the PR branch if not already local
git fetch origin "${BRANCH}:${BRANCH}" 2>/dev/null || git fetch origin "pull/${PR_NUM}/head:${BRANCH}"

git worktree add "${WORKTREE}" "${BRANCH}"
cd "${WORKTREE}/projects/amdsmi"
```

For a new local feature branch:

```bash
BRANCH=<branch-name>

MAIN_CHECKOUT=$(git rev-parse --show-toplevel)
WORKTREE_PARENT=$(dirname "$MAIN_CHECKOUT")
WORKTREE="${WORKTREE_PARENT}/rocm-systems-${BRANCH}"

cd "$MAIN_CHECKOUT"
git worktree add "${WORKTREE}" -b "${BRANCH}" origin/develop
cd "${WORKTREE}/projects/amdsmi"
```

### Shortcut: `new-worktree.sh`

`new-worktree.sh` (this skill's directory) scripts Steps 0–2 — it derives the main
checkout, applies the `rocm-systems-<name>` convention, creates the worktree, and
prints the `cd` target. It hard-codes no user or path, so any rocm-systems checkout
can use it:

```bash
.claude/skills/amdsmi-using-git-worktrees/new-worktree.sh -p 10091                       # rocm-systems-pr10091 from the PR head
.claude/skills/amdsmi-using-git-worktrees/new-worktree.sh apu-fix -b users/me/apu-fix    # new branch off origin/develop
```

Still confirm consent (Step 1) before running it.

**Sandbox fallback:** If `git worktree add` fails with a permission error, tell the user and work in the current directory instead.

## Step 3: Project Setup

Worktrees of `rocm-systems` already have the full source tree — no `npm install` / `pip install` needed for amd-smi work.

If the worktree is for a clean build, invoke the `amdsmi-build-install` skill to produce a baseline build.

## Step 4: Verify Clean Baseline

If the worktree is new, build once to confirm a clean starting state:

```bash
# From the amdsmi/ subdirectory inside the worktree
mkdir -p build && cd build
cmake .. -DBUILD_TESTS=ON -DCMAKE_BUILD_TYPE=RelWithDebInfo
make -j"$(nproc)"
```

If the build fails on `origin/develop` → report the failure, ask whether to proceed or investigate. Do NOT proceed with feature work on top of a broken baseline.

## Quick Reference

| Situation | Action |
|-----------|--------|
| Already in a linked worktree (`GIT_DIR != GIT_COMMON`) | Skip creation, report path + branch |
| In a submodule | Treat as a normal repo |
| PR-based work | `rocm-systems-pr<PR#>` sibling dir |
| Local feature branch | `rocm-systems-<branch>` sibling dir |
| Sandbox blocks `worktree add` | Fall back to in-place, tell the user |
| Build fails on baseline | Report, ask before proceeding |

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Creating a worktree inside the main checkout | Sibling-directory convention only |
| Skipping Step 0 detection | Always detect existing isolation first |
| Creating a worktree without consent | Ask first (unless user already said so) |
| Forgetting to `cd` into `projects/amdsmi` after worktree add | The worktree root is `rocm-systems-pr<N>`, but amd-smi work happens in `projects/amdsmi` |
| Proceeding past a failing baseline build | Stop and report |

## Red Flags — STOP

- Creating a worktree without confirming current isolation status
- Building feature work on a baseline that doesn't compile
- Branching from anything other than `origin/develop` (unless explicitly told otherwise)
- Force-deleting a worktree without consulting `amdsmi-restructure-commits`' finishing flow

## Cleanup

Cleanup happens at the end of the workflow — see the `amdsmi-restructure-commits` skill's "Finishing the Branch" section. Don't remove worktrees inline; that's the finishing skill's job.