GitHub CLI

Este capítulo ha sido escrito basándose en la versión 2.21.1 de _gh

Hoy en díaGitHubes el mayor de todos los repositorios de Git en el mundo. En 2018, Microsoft adquirió GitHub por 7.500 millones de dólares³⁶y, desde entonces, no ha dejado de crecer.

Eso hace queel uso de Git esté muy ligado a GitHuby, por eso, mucha gente lo confunde o cree que es lo mismo. Pero ya hemos visto que no es así y que Git es una tecnología independiente a GitHub, que es donde se guardan los repositorios remotos de Git.

Dicho esto, este capítulo viene a explicarte la línea de comandos deghpara GitHub. Esta línea de comandos te permite interactuar con el repositorio remoto de GitHub.

GitHub CLI 2.0 apareció en agosto del 2021 y entre sus novedades destacan el soporte a GitHub Actions y la posibilidad de usar extensiones

• ^³⁶ https://news.microsoft.com/announcement/microsoft-acquires-github/

Te ayudará a trabajar con tu repositorio Git que está hospedado en GitHub. Por ejemplo, podrás crearPull Requests,Issuesy muchas cosas más desde tu terminal, sin necesidad de ir a la web de GitHub.

Es importante que no confundas la línea de comandos de Gitgitcon la línea de comandos de GitHub gh.

Instalando gh en el sistema...

A diferencia de git, ghno está instalado por defecto en muchos sistemas por lo que es muy probable que tengas que instalarlo para poder utilizarlo. Te dejo aquí las instrucciones de los distintos sistemas operativos:

En macOS

Puedes instalar gh en tu sistema operativo usando Homebrew³⁷ ejecutando el
siguiente comando:

$ brew install gh

Si lo prefieres también puedes usarMacPorts³⁸con el siguiente comando:

$ sudo port install gh

En Linux

para Debian y Ubuntu puedes instalarghcon el gestor de paquetesapt:

$ curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.
gpg | sudo gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyri
ng.gpg

$ echo "deb [arch= $( dpkg --print-architecture ) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/nu
ll

$ sudo apt update
$ sudo apt install gh

ParaFedora, CentOS y Red Hat, puedes instalarghusando el siguiente comando:

• ^³⁷ https://brew.sh/
• ^³⁸ https://www.macports.org/

$ sudo dnf config-manager --add-repo https://cli.github.com/packages/rp
m/gh-cli.repo
$ sudo dnf install gh

En Windows

Lo más sencillo es que descargues el instalador oficial de GitHub desdeaquí³⁹. Descarga el ficherogh_1.x.0_windows_amd64.msi, ejecútalo y sigue los pasos.

• ^³⁹ https://github.com/cli/cli/releases/

Realizando la configuración inicial de gh

Antes poder empezar a usar el comandoghtenemosqueautentificarnosen GitHub. Para ello, ejecuta el comando gh auth login. Verás que te preguntará por tu tipo de cuenta (lo más normal es que uses la de GitHub.com, ya que la de Enterprise Server es para empresas).

$ gh auth login

? What account do you want to log into? [Use arrows to move, typeto f ** ilter] > GitHub.com GitHub Enterprise Server

Después de seleccionar el tipo de cuenta, te preguntará cuál es tu protocolo favorito para trabajar en Git. Elegiremos SSH.

? What is your preferred protocol for Git operations? [Use arrows to m ** ove, typeto filter] HTTPS > SSH

? Upload your SSH public key to your GitHub account? [Use arrows to mo ** ve, typeto filter] > /Users/tu-usuario/.ssh/id_ed25519.pub Skip

? How would you like to authenticate GitHub CLI? [Use arrows to move, ** typeto filter] > Login with a web browser Paste an authentication token

! First copy your one-time code: 1A6D-BECA

• Press Enter to open github.com in your browser…

✓ Authentication complete. Press Enter to continue …

• gh configset -h github.com git_protocol ssh ✓ Configured git protocol ✓ Uploaded the SSH key to your GitHub account: /Users/tu-usuario/.ssh/id_e ** d25519.pub ✓ Logged in as tu-usuario

Usando gh

El comandoghtiene dos niveles de comandos. El primer nivel sería el contexto sobre el que queremos trabajar. Por ejemplo, si queremos trabajar a nivel de repositorios, usaremos gh repo. Entonces, dentro de ese nivel, tendremos una serie de comandos que podremos ejecutar.

Hay muchos contextos disponibles pero nosotros nos vamos a enfocar en los
siguientes:

• repo: Para crear, clonar, hacer fork y ver repositorios.
• issue: Para crear, ver, editar y cerrar issues.
• pr: Para crear, ver, editar y cerrar pull requests.
• gist: Para crear, ver y editar gists.

Otros disponibles son:actions, alias, api, auth, browse, completion, config, extension, help, release, run, secret, ssh-key y workflow

ghfunciona por defecto sobre el repositorio en el que estamos localmente yquetenga un repositorio remoto configurado que sea de GitHub. Si intentas usarlo en un proyecto que es un repositorio de Git válido pero no está enlazado con un repositorio de GitHub remoto te dará el siguiente error:

$ gh issue list
no git remotes found

Si intentas ejecutar el comando en un directorio que no es un repositorio, te dirá lo siguiente:

$ gh issue list
fatal: not a git repository(or any of the parent directories): .git
/usr/bin/git:exitstatus 128

Si te aparece el error: “No default remote repository has been set for this directory”, es porque no tienes un repositorio remoto por defecto. Para solucionarlo, ejecuta gh repo set-defaultdentro de tu directorio de trabajo con un repositorio de GitHub.

pr: Administrando Pull Requests desde la línea de

comandos

LasPull Request(o petición de cambios) sonuna forma de comunicar que quieres hacer llegar unos cambios a un repositorio de GitHub. Estos cambios pueden ser una mejora en el código, una nueva funcionalidad o la solución a un error en el código.

Conghpodemos realizar todas las operaciones posibles sobre lasPull Requestde un repositorio. Fusionarlas, revisarlas, cerrarlas, abrirlas de nuevo, crearlas, modificarlas… ¡y mucho más! Todo desde tu terminal.

A las Pull Request también se les conoce de forma abreviada como PR, por lo que es posible que a veces veas que en el curso me refiero a ellas de esa forma. Además, como verás, se usaprpara el contexto de las Pull Request en el comando gh.

¿Cómo puedo revisar una Pull Request de forma local?

¿Alguien ha creado una Pull Request a tu repositorio de GitHub y te gustaría revisarla fácilmente en tu máquina local? Gracias aghes muy fácil conseguirlo. Sólo tienes que ejecutar el comando:

$ gh pr checkout <número-de-la-pull-request>

remote: Enumerating objects: 22 , done. remote: Counting objects: 100 % ( 22 /22), done. remote: Compressing objects: 100 % ( 8 /8), done. remote: Total 22 (delta 13 ), reused 22 (delta 13 ), pack-reused 0 Unpacking objects: 100 % ( 22 /22), 6 .02 KiB | 342 .00 KiB/s, done. From github.com:tu-usuario/tu-usuario.dev * [new ref] refs/pull/62/head -> responsive-header

Switched to branch 'responsive-header'

Este comando hará por detrástodos los pasos necesarios para sincronizar tu repositorio: Descargar la rama que corresponda con el número que le has pasado y cambiar tu directorio de trabajo por el contenido de la rama que quieres revisar.

De esta forma, podrásprobarqueelcódigodeestaPullRequestescorrectodesde tu máquina local. Muy útil para asegurarte que el código hace lo que se espera.

Si ejecutas el comando pasándole un número dePRque no existe, recibirás el
siguiente error:

$ gh pr checkout 1234
GraphQL error: Could not resolve to a PullRequest with the number of 12
34.

Además de usar el número de la PR como parámetro, también puedes usar la URL deGitHubdelaPullRequesteinclusoelnombredelaramaquelacontiene. Por ejemplo:

# miramos la PR de la rama stylessh:main
$ gh pr checkout stylessh:main

# miramos la PR de esa URL
$ gh pr checkout https://github.com/tu-usuario/codi.link/pull/17

issue: Administrando Issues desde la línea de comandos

Las issues(o problemas) son una forma de comunicar y reportar errores o peticionesdemejoraenelcódigodeunrepositorio. Así que, a la hora de contribuir a proyectos alojados en GitHub, no sólo se logra con código, sino también con la creación y gestión deissues.

Creando unaissuedesde la línea de comandos

Aunque puedes crearissuessi vas a la secciónIssuesdel repositorio en GitHub, a veces no quieres salir de la terminal para lograrlo. Conghes muy sencillo y te ofrece un montón de opciones para que puedas asignarle el problema a la persona adecuada o lo etiquetes muy fácilmente. Sólo tienes que ejecutar el comando:

$ gh issue create

Creating issue in tu-usuario/tu-usuario.dev

? Title

Una vez añades el título, pulsasEnter. Entonces te preguntará si quieres añadir una descripción. Si no quieres añadir una descripción, pulsaEntery seguirás con el siguiente paso.

Aquí puedes añadir metadatos a laissuecomo etiquetas, el proyecto, asignar a una persona, etc. Incluso te da la opción de continuar la creación de la issue directamente en GitHub, abriéndote una nueva ventana en tu navegador. Si prefieres hacerlo por la línea de comandos eventualmente podrás hacerSubmity crear la issue.

Ten en cuenta que el título de la issue no puede estar vacío ni ser de más de 100 caracteres. De lo contrario, te fallará la creación de laissue.

Si no quieres que te pregunte por el título ni la descripción, puedes pasarlos directamente como argumentos y la issue se creará directamente sin ningún asistente y te devolverá la URL con laissuecreada.

# puedes crear una issue con título y descripción

$ gh issue create --title "Missing dependency" --body "The dep react ismissing"

Creating issue in tu-usuario/tu-usuario.dev

https://github.com/tu-usuario/tu-usuario.dev/issues/73

Si quieres puedes crear laissuesin título ni descripción pero pasarle otras opciones. De esta forma, sí te preguntará por el título y la descripción de forma interactiva (si no lo pasas como argumentos) pero ya tendrás algunos metadatos añadidos.

# también puedes crear una issue con etiquetas

$ gh issue create --label "performance,help wanted"

# puedes crearlas de forma separada
$ gh issue create --label bug --label "good first issue"

# puedes asignar la issue a más de una persona
$ gh issue create --assignee dapelu, jelowing

# incluso a ti mismo
$ gh issue create --assignee @me

# y también asignarlo a un proyecto por nombre
$ gh issue create --project "New Version"

Si lo único que quieres es crear una issue desde el navegador pero poder abrir la ventana desde la terminal, también puedes ejecutar gh issue create —web, que te abrirá la ventana de GitHub con laissueen blanco.

Editarissuesdesde la línea de comandos

¿Te has equivocado en algo al crear laissue?¿Quieres añadir un cambio? No te preocupes. Una vez que tienes laIDde la issue o su dirección en GitHub, vas a poder modificar tantas veces como quieras el error reportado y, lo mejor, sin salir de tu terminal.

# Editamos el título y el cuerpo de la issue
$ gh issue edit 42 --title "Editor no funciona "--body "Falla al iniciar :("

# Podemos añadir etiquetas
$ gh issue edit 42 --add-label "bug,help wanted"

# O quitar etiquetas
$ gh issue edit 42 --remove-label "core"

# Cambiar la asignación de la issue

$ gh issue edit 13 --add-assignee @me --remove-assignee camimaya

# También podemos modificar el proyecto asignado
$ gh issue edit 23 --add-project "Next" --remove-project old,v1

# El hito al que pertenece...
$ gh issue edit 23 --milestone "Version 1"

# Podemos añadir el comentario de la issue

$ gh issue edit 23 --body-file body.txt

Como ves, usando el comandoeditde lasissuesno puedes cambiar su estado de abierto a cerrado. Eso es porque, como ya verás más adelante, existe un comando

específico para eso.

Listando y visualizando _issues_

Si tienes un proyecto de código abierto, seguramente te van a llegar muchasissues. Aprender a manejarlas va a ser una de los retos más importantes a los que te vas a enfrentar. Por suerte, con gh, hacerlo es muy fácil si dominas todas las posibilidades que te ofrece.

Lo más básico es, simplemente, mostrar una lista de las que hay con:

# listar las issues del repositorio
$ gh issue list

Showing 3 of 3 open issues in SUI-Components/sui-components

# 1613 Demo PhotoUploader issue with documentation about 1 month ago
#1612 Demo Modal issue with documentation about 1 month ago
#1596 Clean V7 values enhancement about 2 months a\
go

Por defecto te muestra un máximo de 30 issues. Puedes limitarlo usando el parámetro-L.

Esto es lo más básico pero, a partir de aquí, tienes muchas opciones para filtrar, ordenar, etc. Te muestro una lista de ejemplo pero no es una lista completa ya que las combinaciones son demasiadas.

# filtrar issues por etiquetas
$ gh issue list -l "performance "-l "good-first-issue"

# muestra las issues creadas por el usuario vekpol
$ gh issue list --author vekpol

# muestra las issues asignadas a mí
$ gh issue list -a @me

# las issues que ya han sido cerradas asignadas a mí
$ gh issue list --state closed -a @me

# usa una consulta para buscar, filtrar y ordenar las issues
$ gh issue list --search "error no:assignee sort:created-asc"

# abre una nueva ventana con la lista de issues en la web
$ gh issue list --web

# también puedes ver las issues de webs externas

$ gh issue list -R facebook/react -l "good first issue"

¿Quieres tener la salida del comando en formatojson? Prueba a ejecutar este comando gh issue list -R tu-usuario/codi.link —json id, title. Ahora que ves la salida, prueba a añadir otros campos comobody, stateolabelscon otros repositorios, para ver la salida.

Un resumen rápido de las _issues_ que nos interesan

Otra forma de tener un vistazo rápido a lasissuesque más nos pueden interesar de un repositorio es usando el comando gh issue status. La salida nos hará un buen resumen de las issues que tenemos abiertas, asignadas y en las que nos mencionan.

$ gh issue status

Relevant issues in tu-usuario/tu-usuario.dev

Issues assigned to you
# 59 Improve performance about 1 day ago
#74 Mobile version fails about 42 minutes ago

Issues mentioning you
# 35 Wrong icon placement about 3 days ago

Issues opened by you
# 75 Slow installation about 2 minutes ago

Leyendo una _issue_ desde la terminal

También puedes acceder a toda la información de unaissuesin necesidad de abrirla en el navegador. Para ello, ejecuta el comando gh issue viewy te mostrará la información de la issue que le indiques (¡Incluso sus comentarios!). Para ello puedes usar la id de laissueo su URL en GitHub.

# leer la issue usando la id
$ gh issue view 35

Guardar parámetros en localStorage # 35
Open • Sebass83 opened about 1 day ago • 0 comments
Labels: enhancement

Se pueden guardar los parámetros de la URL en el localStorage para
tener un auto guardado. Incluso se podría desactivar desde
dentro de las opciones.

View this issue on GitHub: https://github.com/tu-usuario/codi.link/issues/ ** 35

javigaralva • 7d • Edited • Newest comment

Me parece muy buena idea!( #2)

Ahora, desde la terminal, consigue la lista de problemas reportados en el repositorio facebook/reactusando el comando gh issue listy, después, ejecuta el comando gh issue viewcon la id de la issue que quieras leer. ¿Recuerdas cómo usar el parámetro-R(o—repo) para seleccionar otro repositorio?

Cerrar y eliminar _issues_ de nuestro repositorio congh

A la hora de cerrar lasissuesdesde la terminal, puedes usar tanto laIDde laissue como su URL en GitHub.

# usando la id de la issue
$ gh issue close 74
✓ Closed issue # 74 (Chrome not working)

# usando la URL completa de la issue
$ gh issue close https://github.com/tu-usuario/tu-usuario.dev/issues/75
✓ Closed issue # 75 (Slow initialization of app)

Una vez que la cierras… ¡es posible que te hayas equivocado! Así que la vas a querervolver a abriry esto también lo puedes hacer desde la terminal fácilmente.

# reabrimos la issue 75 usando su id
$ gh issue reopen 75
✓ Reopened issue # 75 (Slow initialization of app)

Si quieres eliminar definitivamente laissuede tu repositorio, puedes usar el comando gh issue delete. No te preocupes al hacerlo, porque el comando viene con un sistema de seguridad en el que te volverá a preguntar el número de laissueque quieres eliminar.

# eliminamos la issue 79 usando la URL
$ gh issue delete https://github.com/tu-usuario/tu-usuario.dev/issues/79
You 're going to delete issue # 75.
? This action cannot be reversed. To confirm,typethe issue number:
75
￿ Deleted issue # 75 (Slow initialization of app).

repo: Administrando un Repositorio desde la línea de

comandos

Los repositorios son una parte fundamental de GitHub, por lo que es importante que puedas administrarlos desde tu terminal. Gracias aghpuedes crear, clonar, editar, eliminar y listar repositorios además de crear bifurcaciones (forks).

Crear un _repositorio_ congh

Muchas veces uso el acceso directo https://repo.new para crear un nuevo repositorio de forma rápida y sencilla. Pero aquí hemos venido a hablar deghy, como no podía ser de otra forma, podemos crear un repositorio desde la terminal y con un montón de posibilidades y opciones.

Si quieres crearlo y que te pregunte paso por paso todas las opciones, sólo tienes que ejecutar el comando gh repo createy te pedirá que le indiques el nombre del repositorio, su descripción, su visibilidad y otras opciones.

Si ejecutas este comando en tu terminal desde un directorio de trabajo que es un repositorio local inicializado con git, este nuevo repositorio remoto creado será añadido como origin.

# crea un repositorio local con el nombre de gallery-slider
$ git init gallery-slider
# entramos en el directorio de trabajo del repo
$ cdgallery-slider
# creamos el repositorio remoto que se añadirá como `origin`
$ gh repo create
# nos hará algunas preguntas sobre el repo a crear y al final...
✓ Created repository tu-usuario/gallery-slider on GitHub
✓ Added remote https://github.com/tu-usuario/gallery-slider.git

Puedes pasarle el nombre que prefieras al repositorio, pero es importante que lo pongas en minúsculas y sin espacios. Así puedes hacer que el repositorio nuevo no tenga el mismo nombre que la carpeta local.

# en la carpeta ~/gallery-slider hacemos
$ gh repo create gallery-slider-wc
✓ Created repository tu-usuario/gallery-slider on GitHub
✓ Added remote https://github.com/tu-usuario/gallery-slider.git

# Puedes usar también otra organización a la que tengas acceso
$ gh repo create my-org/gallery
✓ Created repository my-org/gallery on GitHub
✓ Added remote https://github.com/my-org/gallery.git

Si el directorio en el que te encuentras no es un repositorio local, también puedes inicializarlo con gh repo createdespués de crear el repositorio en GitHub. Simplemente te avisará el comando y tendrás que confirmarlo.

# ejecutamos desde un directorio que no es un repositorio
$ gh repo create new-project
# nos hará unas cuantas preguntas...
? Visibility Public
? Would you like to add a .gitignore? No
? Would you like to add a license? No
? This will create the "new-project "repository on GitHub.
? Continue? Yes
✓ Created repository tu-usuario/new-project on GitHub
# en este punto nos avisa que creará una carpeta nueva

? Create a localproject directory for "tu-usuario/new-project "? Yes

Clonando un _repositorio_ congh

Si quieres clonar un repositorio, puedes hacerlo con gh repo clone. Este comando te permite clonar un repositorio de GitHub y, además, te permite elegir el nombre del directorio donde se clonará el repositorio.

# clonamos el repositorio tu-usuario/tu-usuario.dev
$ gh repo clone tu-usuario/tu-usuario.dev

# clonamos el repositorio tu-usuario/tu-usuario.dev en la carpeta blog
$ gh repo clone tu-usuario/tu-usuario.dev blog

Cloning into ‘blog’… remote: Enumerating objects: 8044 , done. remote: Counting objects: 100 % ( 157 /157), done. remote: Compressing objects: 100 % ( 111 /111), done. remote: Total 8044 (delta 75 ), reused 101 (delta 29 ), pack-reused 7887 Receiving objects: 100 % ( 8044 /8044), 36 .73 MiB | 12 .50 MiB/s, done. Resolving deltas: 100 % ( 4293 /4293), done.

Como ves, no hace falta que le indiques la URL completa del repositorio. Puedes usar el nombre del usuario y el nombre del repositorio directamente.

gist: Administrando _gists_ desde la línea de comandos

Losgistde GitHub son repositorios de código pero pensados para ser pequeños yde uso único. Por ejemplo, una pequeña aplicación que te ayude a hacer una copia de seguridad de tu trabajo o un ejemplo de utilidad que te ayude a comprender un tema.

De hecho existen cientos de miles de estos pequeños extractos de código. Puedes ir a su página para ver todos los que hay disponibles⁴⁰y buscar alguno que pueda interesarte.

Si no quieres tener que abrir al navegador para disfrutar de estosgists, no te preocupes. Conghno sólo vamos a poder crear estos trozos de código, si no que tambiénvamos a poder crearlos y editarlos desde la terminal.

Creando un _gist_ desde la terminal

# publica el fichero 'index.js' como un gist público
$ gh gist create --public index.js

# crea un gist privado con una descripción
$ gh gist create analytics.js -d "Ejemplo de cómo usar Analytics en tu sitio con JS"

# crea un gist que contenga diferentes ficheros
$ gh gist create index.js index.html styles.css

# crea un gist desde el standard input
$ gh gist create -

# crea un gist desde el output de otro comando
$ cat cool.txt | gh gist create

Más comandos para administrar _gists_

Una vez hemos creado nuestrogist, vamos a querer administrarlo de alguna forma. Ya sea verlo, editarlo o borrarlo definitivamente. Veamos una lista de los comandos

⁴⁰https://gist.github.com/discover

disponibles para poder hacerlo:

# muestra el contenido del gist
$ gh gist show <id>

# edita el gist
$ gh gist edit <id>

# borra el gist
$ gh gist delete <id>

# borra el gist y todas sus versiones
$ gh gist delete --force <id>

# clona el gist a tu máquina local
$ gh gist clone <id>