mirror of https://github.com/github/gh-stack.git synced 2026-09-14 20:26:28 +08:00

Files

T

Sameen Karim f880f0d469 Stack number as primary identifier (#178 )

* 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

2026-07-15 12:07:44 -04:00

2.0 KiB

Raw Permalink Blame History

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

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 in the repository root.

2.0 KiB Raw Permalink Blame History

gh-stack: Copilot Instructions

Build and validate

Project layout

Coding conventions

2.0 KiB

Raw Permalink Blame History