Como Não se Afogar em Grandes Pull Requests com gh-stack
Todos já passamos por isso: você está trabalhando em uma feature complexa que toca a API, lógica de backend e frontend. O resultado é um PR gigante com três mil linhas de código. O revisor abre, vê o volume, suspira discretamente e fecha a aba até tempos melhores. Ou pior, dá uma olhada rápida em cinco minutos e escreve "LGTM", perdendo bugs críticos.
Para pouparmos nossos colegas, tentamos dividir as mudanças em pequenos pedaços. Mas então começa o inferno das dependências: branch feature-ui depende de feature-api, que depende de feature-db. Corrija algo no fundo dessa cadeia, e você tem que fazer rebase manual de todos os branches acima, acompanhar os branches base no GitHub e torcer para nada quebrar.
Parece que os engenheiros do GitHub também se cansaram disso e lançaram uma extensão para o CLI deles — gh-stack. Ela automatiza o trabalho com os chamados pull requests "empilhados".
O que são PRs empilhados e por que você precisa deles
A ideia é simples: em vez de uma mudança massiva, você cria uma cadeia de PRs pequenos e logicamente conectados. Cada um subsequente se baseia no anterior.
Pense assim:
- PR #1: Adicionar schema do banco de dados (base:
main). - PR #2: Implementar endpoints da API (base: branch do PR #1).
- PR #3: Construir a interface do frontend (base: branch do PR #2).
Os revisores podem verificá-los individualmente. É mais rápido, mais fácil e mais completo. O problema é que o Git e o GitHub não funcionam nativamente bem com essa estrutura. Se você atualizar o PR #1, tem que "puxar" manualmente as mudanças para todos os outros. gh-stack cuida dessa rotina para você.
Como funciona na prática
A ferramenta é instalada como uma extensão do CLI oficial do GitHub. Se você já tem gh, a instalação leva alguns segundos:
gh extension install github/gh-stack
Criando sua primeira stack
Digamos que você está começando a trabalhar em uma nova tarefa. Em vez do usual git checkout -b, você inicializa uma stack:
gh stack init
Então você faz commits normalmente. Quando a primeira parte lógica está pronta, em vez de criar um branch manualmente, você simplesmente diz:
gh stack add feature-api
Este comando cria um novo branch no topo do atual e imediatamente muda para ele. Você continua escrevendo código. Quando a stack está pronta, um único comando gh stack submit envia tudo para o GitHub. A ferramenta criará múltiplos pull requests e configurará seus base branch corretamente para que cada PR mostre apenas o diff relevante, não uma bagunça de todos os branches anteriores.
Navegação e edições
Uma das funcionalidades mais úteis em gh-stack é a navegação. Esqueceu os nomes dos branches? Sem problema.
gh stack up— sobe um nível na stack.gh stack down— desce para a base.gh stack tree— visualiza toda a estrutura.
Se um revisor pedir para você corrigir algo no primeiro PR, você simplesmente desce (gh stack bottom), faz as alterações e executa gh stack rebase. A mágica é que a ferramenta propaga automaticamente essas mudanças por toda a stack para cima, atualizando todos os branches intermediários. Adeus rebases manuais de cinco branches seguidos.
Gerenciamento via TUI
Para quem prefere controle visual, existe o comando gh stack modify. Ele abre uma interface interativa direto no terminal. Lá você pode:
- Reordenar branches.
- Juntar múltiplos branches em um.
- Remover partes desnecessárias da stack.
- Renomear camadas.
Isso é muito mais intuitivo do que tentar fazer o mesmo através de git rebase -i e trocas intermináveis de branch.
Sincronização e finalização do trabalho
Quando seus PRs começam a fazer merge no branch principal, é hora do gh stack sync. O comando faz várias coisas úteis de uma vez: puxa mudanças de main, atualiza sua stack local e sugere deletar branches de PRs já mergeados.
A propósito, a ferramenta também pode funcionar com agentes de IA. Se você usa automação para geração de código, pode instalar a skill gh skill install github/gh-stack para que o agente entenda sua estrutura de branches e não quebre a stack.
Alguma ressalva?
O projeto está atualmente em Public Preview. Isso significa que para algumas funcionalidades funcionarem (como a exibição bonita de relacionamento de PRs diretamente na interface do GitHub), o recurso precisa estar habilitado para seu repositório. Se ainda não estiver ativo, você pode entrar na lista de espera.
No entanto, mesmo sem o componente server-side, como auxiliar local para gerenciar cadeias de branches, gh-stack já é bastante utilizável.
Para quem é isso
Se você trabalha em uma equipe grande com um processo rigoroso de code review, esta ferramenta vai te poupar horas. Elimina o medo do "descolamento" de branches e permite focar no código em vez da administração do Git.
Se você é o único desenvolvedor em um projeto e faz merge de tudo direto no main, provavelmente não precisa disso. Mas para todos os outros — esta é uma ótima forma de tornar seus PRs amigáveis e fáceis de revisar.
Vale a pena experimentar só pelo comando gh stack alias. Ele cria um alias curto gs, após o qual trabalhar com a stack se torna completamente fluido. Por exemplo, gs push em vez de construções verbosas. Uma ferramenta simples e eficaz dos criadores do próprio GitHub.
Projetos relacionados