checkout · diff
git:20260128.d4d59c8 to git:20261028.c2c0bcf
10 added, 109 removed. Audit A to A.
---
name: checkout
description: Use when checking out a PR, branch, or ref for local work - sets up worktree with context
---
# Git Checkout
- ## Overview
-
- Check out a PR, branch, or ref into an isolated worktree with relevant context.
-
- **Announce:** "Using git:checkout to set up a worktree for {target}..."
-
- ## When to Use
-
- - User wants to review a PR locally
- - User wants to work on a specific branch in isolation
- - User provides PR URL/number or branch name
- - Following `git:inbox` when user picks a PR
-
- ## Input Formats
-
- Accept:
- - Full PR URL: `https://github.com/{owner}/{repo}/pull/{number}`
- - Short PR: `{repo}#{number}` or `#{number}` (infer repo from cwd)
- - PR number only: `{number}` (infer owner/repo from git remote)
- - Branch name: `feature/auth`, `main`, etc.
- - Ref: commit SHA, tag
-
- ## Workflow
-
- ### For PRs
-
- #### 1. Parse PR Reference
-
- ```bash
- # Get owner/repo from current directory if needed
- gh repo view --json owner,name -q '"\(.owner.login)/\(.name)"'
- ```
-
- #### 2. Fetch PR Details
-
- ```bash
- gh pr view {number} --json title,body,author,state,baseRefName,headRefName,url,reviews,reviewRequests
- ```
-
- #### 3. Set Up Worktree
-
- **REQUIRED:** Use `superpowers:using-git-worktrees` skill for directory selection.
-
- ```bash
- # Fetch the PR branch
- git fetch origin {headRefName}
-
- # Create worktree
- git worktree add .worktrees/pr-{number}-{short-desc} origin/{headRefName}
- ```
-
- Naming: `pr-{number}-{2-3-word-description}` (e.g., `pr-1234-add-oauth`)
-
- #### 4. Present Context
-
- ```markdown
- ## PR #{number} Ready for Review
-
- **Title:** {title}
- **Author:** @{author}
- **Branch:** {headRefName} → {baseRefName}
- **URL:** {full_url}
-
- ### Summary
- {1-3 sentence summary from PR body}
-
- ### Files Changed ({count})
- {Grouped by directory}
-
- ### Review Status
- {Existing reviews, requested reviewers}
-
- ---
-
- **Worktree ready at:** `{full_path}`
- ```
-
- ### For Branches
-
- #### 1. Create Worktree
-
- ```bash
- # For existing branch
- git worktree add .worktrees/{branch-slug} {branch}
-
- # For new branch
- git worktree add .worktrees/{branch-slug} -b {branch}
- ```
-
- #### 2. Report Ready
+ Check out a PR, branch, or ref into an isolated worktree, with the context needed to start work or review.
- ```markdown
- **Worktree ready at:** `{full_path}`
- **Branch:** {branch}
- ```
+ Accepts a PR URL, `{repo}#{number}`, `#{number}` or a bare number (infer owner/repo from the git remote), a branch name, or a SHA/tag.
- ## Quick Reference
+ ## PRs
- | Input | Action |
- |-------|--------|
- | PR URL/number | Fetch PR, create worktree, show PR context |
- | Branch name | Create worktree for branch |
- | Ref/SHA | Create worktree at that ref |
+ 1. `gh pr view <number> --json title,body,author,state,baseRefName,headRefName,url,reviews,reviewRequests`
+ 2. `git fetch origin <headRefName>` before creating the worktree.
+ 3. Create the worktree with `superpowers:using-git-worktrees`, which picks the directory and honors the user's worktree tool. Name it `pr-<number>-<2-3-word-description>` (e.g. `pr-1234-add-oauth`).
+ 4. Report: title, author, `head -> base`, full URL, a 1-3 sentence summary of the PR body, changed files grouped by directory, review status (existing reviews, requested reviewers), and the worktree path.
- ## Common Mistakes
+ ## Branches and refs
- | Mistake | Fix |
- |---------|-----|
- | Creating worktree before fetching PR branch | Always `git fetch` first |
- | Generic worktree name | Include PR number AND short description |
- | Missing PR context | Always summarize PR and show review status |
+ Create the worktree the same way (new branch if it doesn't exist yet) and report the path and branch.
## Related
- - `superpowers:using-git-worktrees` - Handles directory selection and verification
- - `git:inbox` - Discover PRs needing review
- - `code-review` - Guide the actual review process
+ - `git:inbox` to find PRs awaiting review, `code-review` for the review itself.