gh-stack: Instructions file for GitHub Copilot

gh-stack: Copilot Instructions

A Go CLI extension (gh stack) for managing stacked branches and pull requests. Uses Cobra for commands, bubbletea/lipgloss for TUI, and stretchr/testify for tests.

Repository operations require Git 2.36+.

Build and validate

go mod download                  # install deps
go build -o gh-stack .           # build
go vet ./...                     # static analysis. Always run before tests.
go run ./scripts/test -workers 4 # full race-enabled suite in isolated processes

Run vet before tests. See CONTRIBUTING.md for canonical/targeted commands and runner details. Do not add t.Parallel to tests that change Git mocks, cwd, or environment variables.

No Makefile, no code generation, no external linter config. Standard Go toolchain only.

Project layout

• cmd/: One Cobra command per file. Each exports <Name>Cmd(cfg *config.Config) with logic in run<Name>().
• internal/git/: Ops interface wrapping git CLI. MockOps for tests. Use ForWorktree(path) for scoped execution, CommonDir() for shared storage, and GitDir() for native per-worktree state. Never use production os.Chdir or SetOps to switch context.
• internal/github/: ClientOps interface (18 methods) for GitHub API. MockClient for tests. Stack operations use the public Stacks REST API (/repos/{owner}/{repo}/stacks); merges use the async merge API (/repos/{owner}/{repo}/pulls/{n}/merge-async) with an explicit merge_action (direct_merge or merge_queue) chosen from the base branch's merge-queue detection. merge_action is optional — omitting it (or sending default) lets the server auto-route (merge queue if one is configured, else direct merge) — but the CLI sends it explicitly so a wrong detection fails loudly instead of silently merging directly.
• internal/config/: Config struct passed to all commands. Holds I/O, colors, and test hooks (SelectFn, ConfirmFn, InputFn, GitHubClientOverride).
• internal/stack/: Shared catalog (<common-dir>/gh-stack, JSON), conservative legacy migration, atomic saves, and short catalog locks.
• internal/worktree/: Origin/owner identities, cleanliness preflight, scoped operations, and touched-ref recovery.
• internal/theme/: GitHub-branded palette (single source of all hex colors), plain-output colorizers, and CanvasOutput, which paints GitHub's canvas behind full-screen TUIs.
• internal/tui/: bubbletea views (stackview, modifyview).