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:

~/.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:

~/.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:

~/.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
• EXAMPLES.md