gh-stack: gerenciar PRs empilhadas com GitHub CLI

Para quem

gh-stack é uma extensão do GitHub CLI para gerenciar branches empilhadas e Pull Requests. Serve para quem já usa GitHub CLI e precisa avançar um conjunto ordenado de branches como uma stack. O resumo também diz que instalar a extensão exige GitHub CLI v2.0+.

O material menciona que você pode instalar o gh-stack skill para um agente de código de IA entender PRs empilhadas e a linha de comando gh stack; o trecho só diz «instalar esse skill» e não dá um segundo comando de instalação, então não invente um instalador que não aparece. O material não lista produtos de agente; não trate isso como recurso exclusivo de um editor. A página oficial do guia é

https://github.com/github/gh-stack

Primeira tentativa em 3 minutos

O comando oficial de instalação é este do trecho:

gh extension install github/gh-stack

Pré-requisito: GitHub CLI já está na máquina e a versão atende o v2.0+ do resumo. Este comando grava uma extensão na máquina, então tem efeitos colaterais. Confirme que o repositório e a conta atuais são o ambiente em que você quer testar a stack e só então instale.

Checagem de baixo risco após instalar: não crie uma branch imediatamente. Primeiro confirme que o comando gh stack já é encontrado pelo CLI. O material explica gh stack init como «começar uma nova stack e criar e fazer checkout da primeira branch»; isso muda a árvore de trabalho, então obtenha confirmação antes de executar:

gh stack init

Sinal de sucesso: após a instalação, o gh reconhece o subcomando stack. Se você confirmou que quer uma nova stack, depois do init o repositório atual tem a nova primeira branch, e mais tarde você pode ver metadados JSON em .git/gh-stack (não commitado). Se quiser só ler o guia primeiro, pare após a instalação bem-sucedida e não faça init.

Casos de uso

Caso 1: começar uma nova branch empilhada. Num repositório com a extensão instalada, confirme que pode mudar de branch e execute gh stack init. O material escreve isso como criar e fazer checkout da primeira branch. O resumo também menciona depois adicionar camadas, fazer push, visualizar e enviar um conjunto de PRs, mas o trecho não dá a grafia completa desses subcomandos seguintes. O critério de conclusão deste caso vai só até «a primeira branch foi criada e está em checkout»; não escreva push ou abrir PR como passos já copiáveis.

Caso 2: conferir onde caem os metadados da stack, para saber o que olhar após um rebase interrompido. O material afirma: os metadados da stack ficam em .git/gh-stack, um JSON que não é commitado no repositório e registra quais branches pertencem a qual stack e em que ordem; o estado de um rebase interrompido fica à parte em .git/gh-stack-rebase-state. Isto é uma checagem somente leitura: abra esses dois caminhos, confirme se os arquivos existem e se o JSON está acompanhando a ordem atual das branches. Não edite esses arquivos à mão a menos que a mesma página dê outros passos; o trecho não dá formato de edição.

Limites de uso

A extensão cobre só o gerenciamento de branches empilhadas e Pull Requests. Metadados ficam em .git/gh-stack e não entram na árvore versionada; o estado de rebase interrompido fica em .git/gh-stack-rebase-state. init cria e faz checkout de uma branch; não é um comando somente leitura.

Não invente um comando de instalação de skill que não aparece no trecho, e não trate adicionar camadas, push, visualizar ou enviar do resumo como uma lista de subcomandos já dada. O material não nomeia clientes nem diz como usar fora do GitHub CLI. Além desta instalação, init e localizações de metadados já escritas, este guia não cobre o resto.