From 7811dad16aae26ec02539dfd35917e4104377ef1 Mon Sep 17 00:00:00 2001 From: devantler <26203420+devantler@users.noreply.github.com> Date: Mon, 20 Apr 2026 16:26:35 +0000 Subject: [PATCH] chore(deps): update copilot skills --- plugins/github/skills/gh-stack/SKILL.md | 63 ++++++++++++++++++++++--- 1 file changed, 57 insertions(+), 6 deletions(-) diff --git a/plugins/github/skills/gh-stack/SKILL.md b/plugins/github/skills/gh-stack/SKILL.md index aa8f28d..a6255b9 100644 --- a/plugins/github/skills/gh-stack/SKILL.md +++ b/plugins/github/skills/gh-stack/SKILL.md @@ -4,10 +4,10 @@ description: | metadata: author: github github-path: skills/gh-stack - github-ref: refs/tags/v0.0.1 + github-ref: refs/tags/v0.0.2 github-repo: https://github.com/github/gh-stack - github-tree-sha: f900e01d90dd042162d0632dc31ee9541dd07841 - version: 0.0.1 + github-tree-sha: f11c787bea0bf060af1d8742464a22cd35aa1630 + version: 0.0.2 name: gh-stack --- # gh-stack @@ -56,11 +56,12 @@ git config remote.pushDefault origin # if multiple remotes exist (skips remo 2. **When a prefix is set, pass only the suffix to `add`.** `gh stack add auth` with prefix `feat` → `feat/auth`. Passing `feat/auth` creates `feat/feat/auth`. 3. **Always use `--auto` with `gh stack submit`** to auto-generate PR titles. Without `--auto`, `submit` prompts for a title for each new PR. 4. **Always use `--json` with `gh stack view`.** Without `--json`, the command launches an interactive TUI that cannot be operated by agents. There is no other appropriate flag — always pass `--json`. -5. **Use `--remote ` when multiple remotes are configured**, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, and `checkout` trigger an interactive remote picker. +5. **Use `--remote ` when multiple remotes are configured**, or pre-configure `git config remote.pushDefault origin`. Without this, `push`, `submit`, `sync`, `link`, and `checkout` trigger an interactive remote picker. 6. **Avoid branches shared across multiple stacks.** If a branch belongs to multiple stacks, commands exit with code 6. Check out a non-shared branch first. 7. **Plan your stack layers by dependency order before writing code.** Foundational changes (models, APIs, shared utilities) go in lower branches; dependent changes (UI, consumers) go in higher branches. Think through the dependency chain before running `gh stack init`. 8. **Use standard `git add` and `git commit` for staging and committing.** This gives you full control over which changes go into each branch. The `-Am` shortcut is available but should not be the default approach—stacked PRs are most effective when each branch contains a deliberate, logical set of changes. 9. **Navigate down the stack when you need to change a lower layer.** If you're working on a frontend branch and realize you need API changes, don't hack around it at the current layer. Navigate to the appropriate branch (`gh stack down`, `gh stack checkout`, or `gh stack bottom`), make and commit the changes there, run `gh stack rebase --upstack`, then navigate back up to continue. +10. **Use `gh stack link` for external tool workflows.** When branches are managed by an external tool (jj, Sapling, etc.), use `gh stack link branch-a branch-b`. `link` does not rely on local tracking state and is intended for API-driven PR and stack management. Always provide at least 2 branch names or PR numbers. **Never do any of the following — each triggers an interactive prompt or TUI that will hang:** - ❌ `gh stack view` or `gh stack view --short` — always use `gh stack view --json` @@ -539,6 +540,7 @@ gh stack submit --auto --draft - Pushes all active (non-merged) branches atomically (`--force-with-lease --atomic`) - Creates a new PR for each branch that doesn't have one (base set to the first non-merged ancestor branch) - After creating PRs, links them together as a **Stack** on GitHub (requires the repository to have stacks enabled) +- If stacks are not available (exit code 9), the repository does not have stacked PRs enabled. In interactive mode, `submit` offers to create regular (unstacked) PRs instead. In non-interactive mode, it exits with code 9. - Syncs PR metadata for branches that already have PRs **PR title auto-generation (`--auto`):** @@ -554,6 +556,54 @@ gh stack submit --auto --draft --- +### Link branches as a stack (no local tracking) — `gh stack link` + +Link PRs into a stack on GitHub without creating any local tracking state. This is the recommended approach if you are managing stacked branches with other tools (jj, Sapling, git-town) and want to simply create GitHub Stacked PRs via an API. + +``` +gh stack link [flags] [...] +``` + +```bash +# Link branches into a stack (pushes, creates PRs, creates stack) +gh stack link branch-a branch-b branch-c + +# Use a different base branch and create PRs as drafts +gh stack link --base develop --draft branch-a branch-b branch-c + +# Link existing PRs by number +gh stack link 10 20 30 + +# Add branches to an existing stack of PRs +gh stack link 42 43 feature-auth feature-ui +``` + +| Flag | Description | +|------|---------| +| `--base ` | Base branch for the bottom of the stack (default: `main`) | +| `--draft` | Create new PRs as drafts | +| `--remote ` | Remote to push to (use if multiple remotes exist) | + +**Behavior:** + +- Arguments are provided in stack order (bottom to top) +- Each argument can be a branch name or a PR number. Numeric arguments are tried as PR numbers first; if no PR with that number exists, the argument is treated as a branch name +- Branch arguments are pushed to the remote automatically (non-force, atomic) +- For branches without open PRs, new PRs are created with auto-generated titles and the correct base branch chaining (first branch uses `--base`, subsequent branches use the previous branch) +- Existing PRs whose base branch doesn't match the expected chain are corrected automatically +- If the PRs are not yet in a stack, a new stack is created. If some PRs are already in a stack, the stack is updated (additive only — existing PRs are never removed) +- Does **not** create or modify any local state + +**Output (stderr):** + +- `Pushing N branches to ...` +- `Found PR #N for branch ` for branches with existing PRs +- `Created PR #N for (base: )` for newly created PRs +- `Updated base branch for PR #N to ` when base branches are corrected +- `Created stack with N PRs` or `Updated stack to N PRs` + +--- + ### Sync the stack — `gh stack sync` Fetch, rebase, push, and sync PR state in a single command. This is the recommended command for routine synchronization. @@ -570,7 +620,7 @@ gh stack sync [flags] 1. **Fetch** latest changes from the remote 2. **Fast-forward trunk** to match remote (skips if already up to date, warns if diverged) -3. **Cascade rebase** all stack branches onto their updated parents (only if trunk moved). Handles squash-merged PRs automatically. If a conflict is detected, **all branches are restored** to their pre-rebase state and the command exits with code 3 — see [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) for the resolution workflow +3. **Cascade rebase** all stack branches onto their updated parents (only if trunk moved). Handles merged PRs automatically. If a conflict is detected, **all branches are restored** to their pre-rebase state and the command exits with code 3 — see [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) for the resolution workflow 4. **Push** all active branches atomically 5. **Sync PR state** from GitHub and report the status of each PR @@ -625,7 +675,7 @@ gh stack rebase --abort **Conflict handling:** See [Handle rebase conflicts](#handle-rebase-conflicts-agent-workflow) in the Workflows section for the full resolution workflow. -**Squash-merge detection:** If a branch's PR was squash-merged on GitHub, the rebase automatically handles this and correctly replays commits on top of the merge target. +**Merged PR detection:** If a branch's PR was merged on GitHub, the rebase automatically handles this using `--onto` mode and correctly replays commits on top of the merge target. **Rerere (conflict memory):** `git rerere` is enabled by `init` so previously resolved conflicts are auto-resolved in future rebases. @@ -783,6 +833,7 @@ gh stack unstack feature-auth | 6 | Disambiguation required | A branch belongs to multiple stacks. Run `gh stack checkout ` to switch to a non-shared branch first | | 7 | Rebase already in progress | Run `gh stack rebase --continue` (after resolving conflicts) or `gh stack rebase --abort` to start over | | 8 | Stack is locked | Another `gh stack` process is writing the stack file. Wait and retry — the lock times out after 5 seconds | +| 9 | Stacked PRs unavailable | The repository does not have stacked PRs enabled. `submit` will offer to create regular (unstacked) PRs in interactive mode | ## Known limitations