gh stack: extensão do GitHub CLI para PRs empilhados com integração de IA

O que é

gh stack é uma extensão oficial do GitHub CLI para gerenciar stacked PRs - cadeias de pull requests pequenos e encadeados, onde cada PR tem como base o branch do PR imediatamente abaixo. A ferramenta automatiza a criação de branches, rebases em cascata, configuração correta das bases de cada PR e a navegação entre camadas.

Instalação: gh extension install github/gh-stack (requer gh v2.0+). Há também um skill para agentes de IA: gh skill install github/gh-stack.

Como funciona

Um stack é uma lista ordenada de branches. O branch mais próximo do trunk (geralmente main) é o "bottom"; o mais distante é o "top". Cada branch herda do anterior. Ao submeter, gh stack cria um PR por branch, com a base de cada PR apontando para o branch abaixo, e os vincula como um Stack no GitHub.

Os metadados ficam em .git/gh-stack (JSON local, não commitado).

Principais comandos

Comando	Função
gh stack init	Inicia um novo stack (interativo ou com nomes explícitos)
gh stack add	Adiciona um branch no topo; flags -Am combinam stage + commit + criação de branch em um só passo
gh stack checkout	Faz checkout por número de stack, PR, URL ou branch; modo interativo com picker
gh stack rebase	Fetch + rebase em cascata; suporta --continue, --abort, --downstack, --upstack, --no-trunk
gh stack modify	TUI para reestruturar o stack: drop, fold, insert, rename, reorder
gh stack sync	Fetch + rebase + push + sincronização de PRs + criação/atualização do stack remoto, tudo em um comando
gh stack push	Push de todos os branches ativos com --force-with-lease
gh stack submit	Push + criação/atualização de PRs + criação do stack no GitHub; editor TUI com preview markdown
gh stack link	Vincula PRs em um stack no GitHub sem tracking local (útil para quem usa jj, Sapling, git-town etc.)
gh stack merge	Merge de um ou mais PRs empilhados em operação all-or-nothing; suporta merge queue
gh stack view	Visualiza o stack atual
gh stack unstack	Remove o stack do tracking local e/ou do GitHub

Navegação

up, down, top, bottom, trunk e switch movem entre camadas sem precisar lembrar nomes de branch.

Workflow abreviado

Com gh stack add -Am "mensagem", o fluxo se reduz a: escrever código → um comando que faz stage, commit e cria o branch (nome auto-gerado em formato data+slug). Não é necessário rodar git add nem git commit separadamente.

Integração com IA

O skill github/gh-stack pode ser instalado para que agentes de código (como Copilot) entendam e operem com stacked PRs via CLI.

Outros detalhes

• Licença MIT.
• Códigos de saída específicos para cada tipo de erro (conflito de rebase, falha de API, stack travado por outro processo, etc.).
• Tema do terminal detectado automaticamente (dark/light); configurável via GH_STACK_THEME.
• gh stack alias instala um atalho (padrão: gs) para digitar menos.