Se você usa o Github no dia e ainda não conhece a CLI do Github, eu recomendo que você continue lendo esse artigo. Hoje vamos aprender como aumentar nossa produtividade e qualidade de vida ao trabalhar com issues, pull requests, actions, e mais!

Instalação

Antes de tudo, precisamos instalar a CLI para podermos usar ela, como existem diversos sistemas operacionais neste belo mundo, deixarei aqui um link para o guia de instalação do próprio Github.

Com a ferramenta instalada, podemos verificar a versão com o comando:

gh --version

Autenticando

Depois de instalado, precisamos nos autenticar para conseguir desfrutar da ferramenta, isso é feito com o comando:

gh auth login

Para verificar que está logado, use o comando:

gh auth status

Uma mensagem deve aparecer dizendo que você esta logado no github na sua conta.

Repositórios

Com a CLI do Github, conseguimos clonar, dar fork, listar, ver um repositório, e muito mais.

Digamos que gostaríamos de ver todos nossos repositórios, podemos usar o comando gh repo list.

Esse é o output do comando, uma tabelinha bem simpática que nos mostra os nomes, descrições e algumas outras informações de todos os meus repositórios, note que ele diz que está mostrando 30 de 31, isto é porque esse comando só mostra repositórios nos quais eu sou o dono, o 31º é um repositório que eu sou somente contribuidor, por isso não é mostrado.

Podemos também criar um repositório, com gh repo create, esse comando ajuda muito a simplificar o processo de criar e configurar um repositório totalmente novo:

Clonar um repositório também é simples, podemos fazer do jeito que já estamos acostumados com git, usando a URL do repositório:

Ou melhor ainda, fazendo gh repo clone OWNER/REPO:

Para fazer forks, com gh repo fork, a sintaxe é a mesma.

Com esse comando, podemos ainda arquivar, deletar, renomear e sincronizar repositórios e mais!

Issues

Diariamente trabalhamos muito com issues diferentes, a CLI também facilita a nossa vida nesse quesito, tirando a necessidade de sair do terminal para abrir/ver/listar/comentar etc.

Como é de se esperar, para criar uma issue, usamos gh issue create:

Analogamente, se quisermos ver as issues criadas, usamos um gh issue list:

Também é possível filtrar issues com uma label específica, podemos usar a flag --label, por exemplo para ver só as issues com a label "bug", podemos fazer gh issue list --label=bug (no meu caso a única issue já é de bug, mas funciona!).

Para conseguir mais informações de uma issue específica (por exemplo, a issue de verdade ao invés de só o título e label), usamos o comando gh issue view <numero_issue>:

Nesse caso as informações são facilmente entendidas pelo terminal mesmo, entretanto, as vezes temos mídias ou textos maiores e ver a issue pelo github seria melhor, para isso podemos usar a flag --web.

É possível comentar em issues abertas usando o comando gh issue comment <numero_issue>:

Adicionalmente, também é possível fechar, reabrir, deletar, fixar issues e muito mais.

Pull requests

De longe, o que eu mais gosto ao usar a CLI, é o quanto ela simplifica trabalhar com pull requests, por exemplo, digamos que temos uma nova branch com alterações já commitadas e agora queremos criar uma PR para o repositório, ao invés de passar pela dor de cabeça de subir uma nova branch e criar pelo site, podemos simplesmente fazer gh pr create.

Se precisarmos adicionar algum tipo de mídia, podemos simplesmente continuar no browser, mas toda a informação já vai estar lá.

Assim como em issues, também podemos usar gh pr list e gh pr view, para listar todos os pull requests e ver mais detalhes sobre uma específica respectivamente.

Imagine que alguém acabou de abrir um PR no see repositório, e agora? como testar o código? É possível dar um checkout localmente com gh pr checkout <numero_pr>, assim seu git vai criar uma nova branch no seu repositório local, com todas as mudanças apresentadas no pull request:

Também é possível comentar em um pr com gh pr comment <numero_pr>:

Agora digamos que você tenha sim checks configurados para nova pull requests, como linters ou testes automatizados, é possível verificar a situação de um pr específico com gh pr checks <numero_pr>:

Ademais, também podemos fazer review, marcar um pull request como pronto para review, fechar, reabrir, dar merge, e mais, só pelo terminal.

Apelidos

Como qualquer ferramenta de terminal, é sempre bom criar aliases (apelidos) para comandos que você usa frequentemente, podemos fazer isso usando o comando gh alias set. Por exemplo, vamos criar um alias chamado "bugs", que vai nos mostrar só as issues com a label "bug", para alcançar isso basta digitar no terminal:

gh alias set bugs 'issue list --label=bug'

Agora podemos a qualquer momento digitar "gh bugs" no terminal e ver todas as issues relacionadas :)

Adicionalmente, podemos deletar um alias existente com gh alias delete <nome> ou ver todos os alias criados com gh alias list.

Actions

Se você usa Github Actions, um outro poder da CLI é a habilidade de controlar e ver informações relevantes diretamente no terminal, com gh run e gh workflow, a diferença é que workflowse refere aos arquivos e run as runs que as actions já tiveram.

Para listar todas as recentes runs, usamos gh run list:

Também podemos ver detalhes de uma run ou jobs dela usando gh run view:

O mesmo vale para workflow, porém, com esse subcomando também podemos usar enable e disable, ativar e desativar um arquivo de workflow específico.

Caso seu workflow receba o evento workflow_dispatch, é possível ativar ele manualmente com o comando:

gh workflow run

Descobrindo mais

Apenas vimos a superfície de o que a CLI do Github é capaz de fazer, alguns dos outros recursos que podemos manipular com essa ferramenta incluem: releases, projects, organizations, labels, gists, variáveis do Github Actions e mais!

Para entender melhor como ela pode te ajudar no seu dia a dia como desenvolvedor, recomendo explorar os comandos existentes com gh help:

Note que nossos comandos de alias também aparecem por aqui, o que é uma adição bem legal.

Caso nossa dúvida seja acerca de um comando ou subcomando específico, podemos sempre usar a sintaxe gh help <comando> <subcomando>, como, por exemplo:

Conseguimos uma descrição super detalhada de exatamente o que esse comando faz, as flags disponíveis, os apelidos, exemplos e mais informações!

Extensões

Toda boa ferramenta precisa ter extensões feitas pela comunidade, e aqui não é diferente, temos diversas extensões oficiais e feitas pela comunidade para turbinar ainda mais sua CLI. Para começar use o comando:

gh extensions browse

Aqui podemos ver todas as extensões, ver seus repositórios e instalar elas se quisermos, se você quer achar uma extensão específica, você pode usar o subcomando search:

Instalou uma extensão e agora decidiu que não quer mais ela? Tudo bem, basta usar o comando gh extensions list para ver todas as extensões instaladas e gh extensions remove para remover uma delas:

Conclusão

Espero que você tenha gostado desse artigo! Eu pessoalmente uso essa ferramenta diariamente e me ajudou muito, principalmente em projetos open source, espero que possa te ajudar também.

Caso queira ler mais sobre, aqui está o manual oficial.

Se tiver alguma dúvida, sugestão ou feedback, sinta-se à vontade para deixar um comentário, ficarei feliz em responder, obrigado por ler!