mirror of
https://github.com/github/gh-stack.git
synced 2026-09-14 20:26:28 +08:00
Sameen Karim
f880f0d469
* Support addressing a stack by its stack number checkout now interprets a bare integer as a stack number first (the identifier shown in the github.com stack UI), falling back to a locally tracked PR number, then a PR number discovered from GitHub, then a branch name. A new checkoutStackByNumber resolves the stack via GetStack and checks out its top-most unmerged branch; the reconcile/import logic is shared with the PR-number path. unstack gains an optional <stack-number> positional argument to unstack a specific locally tracked stack instead of the current one. Copilot-Session: 03673c26-a245-42da-93ed-dfcebc92a740 * Surface the stack number in output and TUIs Show the human-facing stack number wherever it is known: - Append a "(stack #N)" label to submit, link, checkout, and unstack success messages. - Add a "Stack #N" header line to the view command (short and static) and the stackview TUI header. - Add a "Stack #N" info line to the submit TUI header when submitting an already-created stack. Copilot-Session: 03673c26-a245-42da-93ed-dfcebc92a740 * Update docs and agent instructions for the new API - cli.md: document checkout/unstack by stack number and drop the "PATs are not supported" note (any gh-authenticated user can now run stack operations). - quick-start.md: drop the PAT-not-supported note. - AGENTS.md / copilot-instructions.md: ClientOps is now 13 methods over the public Stacks REST API; remove the TokenForHostFn test hook; note the stack file's id/number identity. - SKILL.md: add checkout/unstack-by-stack-number quick references. Copilot-Session: 03673c26-a245-42da-93ed-dfcebc92a740 * address review comments
37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
# 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.
|
|
|
|
## Build and validate
|
|
|
|
```sh
|
|
go mod download # install deps
|
|
go build -o gh-stack . # build
|
|
go vet ./... # static analysis. Always run before tests.
|
|
go test -race -count=1 ./... # tests with race detection
|
|
```
|
|
|
|
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 (52 methods) wrapping git CLI. `MockOps` for tests. Package-level functions delegate to swappable `ops` variable.
|
|
- `internal/github/`: `ClientOps` interface (13 methods) for GitHub API. `MockClient` for tests. Stack operations use the public Stacks REST API (`/repos/{owner}/{repo}/stacks`).
|
|
- `internal/config/`: `Config` struct passed to all commands. Holds I/O, colors, and test hooks (`SelectFn`, `ConfirmFn`, `InputFn`, `GitHubClientOverride`).
|
|
- `internal/stack/`: Stack file (`.git/gh-stack`, JSON) management with file locking.
|
|
- `internal/tui/`: bubbletea views (`stackview`, `modifyview`).
|
|
|
|
## Coding conventions
|
|
|
|
- Return typed `ExitError` sentinels (codes 1-10 in `cmd/utils.go`) from `RunE`. Never call `os.Exit()` directly.
|
|
- Check errors with `var exitErr *ExitError; errors.As(err, &exitErr)`.
|
|
- Table-driven tests with `t.Run()` subtests.
|
|
- Use `config.NewTestConfig()` for test configs with captured I/O.
|
|
- Mock git: `restore := git.SetOps(&git.MockOps{...}); defer restore()`. Always defer restore.
|
|
- Mock GitHub: `cfg.GitHubClientOverride = &github.MockClient{...}`.
|
|
- Mock prompts: set `cfg.SelectFn`, `cfg.ConfirmFn`, or `cfg.InputFn`.
|
|
- Load stack files with `stack.Load(dir)` after writing to get correct checksums.
|
|
|
|
For full architecture details, see [AGENTS.md](../AGENTS.md) in the repository root.
|