GitHub desde la línea de comandos

Sin importar el lenguaje que usamos para programar la línea de comandos es una herramienta que nos permite trabajar de manera más rápida y productiva. Cambiar entre la terminal y la web va en contra de esto. En octubre de 2019 se empezó a trabajar¹ con Github CLI para reducir el cambio de contexto entre GitHub web y la máquina local.

¿Qué es GitHub CLI?

Github CLI es la herramienta oficial de código abierto para ejecutar todo el flujo de trabajo en GitHub en la línea de comandos. Nos permite interactuar con repositorios, issues, pull request y más².

GitHub @github

GitHub CLI 1.0 is here Take GitHub to the command line and interact with repositories, issues, pull requests, releases, and more. ✓ Free and open source ✓ Available for macOS, Windows, Linux ✓ GitHub Enterprise Server supported Download it now: github.blog/2020-09-17-git…

8,029

81 personas están hablando de esto

Instalación y autenticación

GitHub CLI se descarga desde su página oficial. Está disponible para MAC Windows Linux y en paquetes binarios.

Github CLI es interactivo con cada uno de sus comandos que nos guiarán a lo que queramos hacer. Una vez instalado podemos iniciar sesión con gh auth login y seguir las instrucciones:

? What account do you want to log into? GitHub.com
- Logging into github.com
? How would you like to authenticate? Paste an authentication token

Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo' and 'read:org'.
? Paste your authentication token: ****************************************
? Choose default git protocol SSH
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
✓ Logged in as MarcoMadera

Otros subcomandos que también se pueden usar con gh auth:

• gh auth logout: Salir de la sesión.
• gh auth refresh: Actualizar las credenciales.
• gh auth status: Verificar el estado de la autenticación.

Comandos

La estructura de los comandos siguen el mismo patrón gh <comando> <acción> [flags] y pueden ser los siguientes:

Repositorios

Para crear repositorios tenemos el comando gh repo create seguido del nombre del repositorio. Su versión web sería el siguiente atajo repo.new, que con GitHub CLI podemos decirle adiós.

C:\Users\marco\repositorios>gh repo create github-cli
? Visibility Private
? This will create 'github-cli' in your current directory. Continue? Yes
✓ Created repository MarcoMadera/github-cli on GitHub
? Create a local project directory for MarcoMadera/github-cli Yes
Initialized empty Git repository in C:/Users/marco/repositorios/github-cli/.git/
✓ Initialized repository in './github-cli/'

C:\Users\marco\repositorios>cd github-cli

C:\Users\marco\repositorios>github-cli>

Para ver repositorios utilizamos gh repo view seguido del nombre del repositorio de esta forma usuario/repositorio. Se puede observar la descripción del repositorio y el contenido del archivo README.md.

Los flags que recibe pueden ser por ejemplo -w o --web para ver el repositorio en la web. Si no incluye un nombre de repositorio se verá el repositorio que está en el directorio actual.

C:\Users\marco\repositorios\github-cli>gh repo view
MarcoMadera/github-cli
No description provided

  ## GitHub CLI

  Github CLI es la herramienta oficial de código abierto para ejecutar todo el flujo de trabajo en github desde la línea de comandos.

  ### Ver los repositorios

    $gh repo view [<repository>] [flags]

  Con este comando se puede observar la descripción del repositorio y el contenido del archivo README.md.

Podemos clonar un repositorio propio o de otro usuario. Para clonar repositorios propios se usa el comando gh repo clone seguido del nombre del repositorio. Para clonar repositorios de otros usuarios es el mismo comando seguido del usuario/repositorio.

C:\Users\marco\repositorios>gh repo clone github-cli
Cloning into 'github-cli'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 3 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
 
C:\Users\marco\repositorios>cd github-cli
 
C:\Users\marco\repositorios\github-cli>

Para hacer fork de un repositorio funciona de la misma manera que clonar un repositorio, el comando fork gh repo fork seguido del repositorio. Si no se provee de ningún repositorio, hace un fork del proyecto actual. Lo que es bueno se quiere empezar a arreglar bugs o realizar una nueva mejora rápidamente.

Pull Request

El comando para pull request es pr seguido de una acción que pueden ser una de las siguientes:

Para crear pull request podemos usar gh pr create. Para agregar directamente un título usamos el flag --title, para el contenido el flag --body y para agregar a alguien para que lo revise el flag --reviewer seguido del usuario.

C:\Users\marco\repositorios\github-cli>gh pr create --title "Como crear un pr" --body "contenido"

? Where should we push the 'rp branch? MarcoMadera/github-cli

Creating pull request for rp into master in MarcoMadera/github-cli

Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
remote:
remote: Create a pull request for 'rp' on GitHub by visiting:
remote: https://github.com/MarcoMadera/github-cli/pull/new/rp
remote:
To github.com:MarcoMadera/github-cli.git
 * [new branch]    HEAD -> rp
Branch 'rp' set up to track remote branch 'rp' from 'origin'.

Con gh pr list seguido de los flags podemos listar pull request. Los flags se pueden usar como filtros. --limit seguido del número limita a la lista. --state y --label seguidos por el valor muestra solo las pr que coincidan.

Para ver pull request se usa gh pr view seguido del número del pull request o directamente la URL.

C:\Users\marco\repositorios>gh pr view
Update README.md
Open · MarcoMadera want to merge 1 commit into rp from master

View this pull request on GitHub: https://github.com/MarcoMadera/github-cli/pull/1

Las demás acciones funcionan de manera similar. gh pr status muestra el estado de las pr en las que participas. GitHub CLI sigue mucho este patrón, revisa el funcionamiento de las acciones listadas anteriormente.

Issues

El comando para manejar issues es issue seguido de una acción que pueden ser una de las siguientes:

Para crear issues se usa el comando gh issue create. Para agregar directamente un título usamos el flag --title, para el contenido el flag --body.

C:\Users\marco\repositorios\github-cli>gh issue create --title "título" --body "contenido" --label "bug"

Creating issue in MarcoMadera/github-cli

https://github.com/MarcoMadera/github-cli/issues/2

Para ver issues se usa gh issue view seguido del número del pull request o directamente la URL.

Para listar issues se usa gh issue list. Los flags se pueden usar como filtros: --limit seguida del número limita a la lista, --author, --label, --assignee seguidos por el valor muestra solo las issues que coincidan.

C:\Users\marco\repositorios\github-cli>gh issue list --label "bug"

Showing 1 of 1 issue in MarcoMadera/github-cli that matches your search

2 título (bug)    about 5 minutes ago

C:\Users\marco\repositorios>gh issue view 2
título
Open · MarcoMadera opened about 5 minutes ago · 0 comments

Labels: bug

  contenido

View this issue on GitHub: https://github.com/MarcoMadera/github-cli/issues/2

Gist

El comando para manejar los gists es gist seguido de una acción que pueden ser una de las siguientes:

Para crear un gist nuevo se hace a través del siguiente comando: gh gist create seguido del nombre de uno o varios archivos separados por espacio. Por defecto los gist son privados, se pueden hacer públicos con el flag -public.

Para editar ver o borrar un gists es con gh gist edit gh gist view o gh gist delete respectivamente seguido del ID del gist o directamente la URL.

Alias

Los aliases son declaraciones de una palabra como un comando extendible, un shortcut al comando. Para manejarlos se usa el comando alias seguido de una acción que pueden ser una de las siguientes:

Para crear un alias se hace con el comando gh alias set seguido del nombre del alias a utilizar como shortcut y la expansión del comando. Para crear una lista de mis bugs sería el siguiente comando gh alias misbugs='gh issue list -a "MarcoMadera" -l "bug"'

C:\Users\marco\repositorios>gh alias set cr "repo create"
- Adding alias for cr: repo create
✓ Added alias.

C:\Users\marco\repositorios\github-cli>gh alias list
co: pr checkout
cr: repo create

API

Github API es poderoso, con gh api se pueden hacer llamadas HTTP a REST o GraphQL API. Se usa con el comando gh api seguido del endpoint que puede ser una URL absoluta o la representación de un repositorio de la siguiente manera de ejemplo repos/user/repo/releases. El método que usa por defecto es GET, se puede cambiar con el flag --method.

C:\Users\marco>gh api https://marcomadera.com/api/now-playing
{
  "artist": "Logic",
  "songUrl": "https://open.spotify.com/track/25F6MWrnFBCXVnpN4n76EK",
  "title": "Keanu Reeves",
  "cover": "https://i.scdn.co/image/ab67616d00004851c27ad6f3930a857177ba33dc",
  "listening": true,
}

Conclusión

Github CLI reduce la necesidad de abrir la Página de Github después de hacer commits y push de código. Por lo que es de gran ayuda para ahorrar tiempo. A día de hoy es la versión 1.0.0 y trae la mayoría de características de GitHub.