# Create Worktree

> Creates or adopts a git worktree from a pinned remote branch or an exact local commit, returning a JSON receipt. Use when a user asks to create a worktree, start a bug or feature branch, adopt an existing worktree, bootstrap a stacked feature package, or create an unpushed final-integration worktree.

- Skill: `abchoudh-amd/create-worktree` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add abchoudh-amd/create-worktree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/abchoudh-amd/create-worktree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: abchoudh-amd (https://skillmd.com/u/abchoudh-amd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/abchoudh-amd/create-worktree

---


# Create Worktree

Run `~/.cursor/skills/create-worktree/scripts/setup-worktree.sh`. The helper
writes commands and diagnostics to stderr and exactly one canonical JSON receipt
to stdout.

## Exact feature-workflow invocation

Resolve the remote base OID first, then pass the feature workflow's exact branch
and absolute worktree path:

```bash
~/.cursor/skills/create-worktree/scripts/setup-worktree.sh \
  --repo /home/user/dev/rocm-systems \
  --branch users/example/feature/1-export-serializer \
  --path /home/user/dev/feature/1-export-serializer \
  --base-branch origin/rocprofiler-compute-develop \
  --base-revision 0123456789abcdef0123456789abcdef01234567 \
  --sparse-path projects/rocprofiler-compute
```

For an unpushed final-integration package, resolve only the exact local commit.
Pass the approved predecessor/target branch as a logical label; the helper does
not resolve that label or perform a Git remote lookup, fetch, or push:

```bash
~/.cursor/skills/create-worktree/scripts/setup-worktree.sh \
  --repo /home/user/dev/rocm-systems \
  --branch users/example/feature/4-report-output \
  --path /home/user/dev/feature/4-report-output \
  --local-base \
  --base-branch users/example/feature/3-analysis-routing \
  --base-revision 89abcdef0123456789abcdef0123456789abcdef \
  --no-push \
  --sparse-path projects/rocprofiler-compute
```

Use `--dry-run` first when checking a planned path or branch. Capture stdout as
the receipt value; do not scrape stderr or write a receipt file into the target
repository. Feature workflow callers pass the JSON directly to their state
transition and persist its digest there.

## Workflow

1. Inspect the physical repository root, remote, exact base branch, full base
   OID, requested branch, and absolute destination.
2. Run with `--dry-run` and inspect the planned commands plus JSON receipt.
3. Run without `--dry-run`. Remote mode fetches the exact base before creation
   and can publish normally. Local mode verifies the existing local commit,
   creates at that OID, disables lazy object fetching, and never runs a Git
   remote lookup, fetch, or push.
4. Preserve the receipt returned on stdout. Confirm `status=created`, the exact
   base/head revisions, upstream, sparse state, and clean worktree state.
5. If recovering an already registered worktree, rerun the exact request with
   `--adopt-existing`. Adoption never means "use whatever is there"; every
   physical path, repository, branch, and ancestry invariant must match. A clean
   worktree still at the exact base with no upstream may complete sparse setup
   that was interrupted before configuration finished.

## Legacy shorthand

The historical positional form remains available:

```bash
~/.cursor/skills/create-worktree/scripts/setup-worktree.sh memory_pool_tracking feature
~/.cursor/skills/create-worktree/scripts/setup-worktree.sh pc_sampling bug
```

It derives `users/abchoudh/<name>` and `$HOME/dev/<name>` (adding `_bug` for a
bug). Prefer explicit `--branch` and `--path` in controlled workflows.

## Safety rules

- Require a physical repository root. The destination parent must be a physical
  directory, or one creatable level inside one. Reject symlinked roots, relative
  explicit paths, filesystem-root destinations, and worktrees belonging to
  another common Git directory.
- Group a stacked feature run under one feature directory. Every package
  worktree goes in `<worktree-root>/<feature-stem>/`, one subdirectory per
  package named for the final segment of that package's branch, so the layout on
  disk mirrors the branch namespace. The helper creates that feature directory on
  the first package; it never creates two missing levels.
- Pin feature work to `--base-revision`. Fail if the remote branch has drifted
  or changes while being fetched.
- Require `--base-branch`, `--base-revision`, and `--no-push` with
  `--local-base`. Treat the branch as an exact logical label, verify the OID is
  a local commit, require Git 2.45+ no-lazy-fetch support, and fail when promised
  checkout objects are not already local instead of fetching them.
- Refuse existing paths or local branches during creation. Remote mode also
  rejects an existing target remote branch and fails if that absence cannot be
  verified. Use `--adopt-existing` only for deliberate recovery.
- Never force-push. The helper uses an explicit branch refspec and verifies the
  remote OID and upstream after a normal push.
- Use `--no-push` only when the caller intentionally owns later publication.
- Use `--no-sparse` for a full checkout. Otherwise, the default sparse path is
  `projects/rocprofiler-compute`. Sparse paths are lexically normalized to one
  safe canonical path, and actual cone-mode state is verified before success.
- Treat stdout as a machine interface. Human-readable output belongs to stderr.
- Accept only `create/created` and `adopt/adopted` for non-dry receipts. Dry-run
  preserves the requested action (`create` or `adopt`) with `status=planned`.

## Additional resources

- [REFERENCE.md](REFERENCE.md)
- [EXAMPLES.md](EXAMPLES.md)