GitHub

GitHub es una plataforma que permite alojar repositorios Git en Internet y proporciona herramientas para compartir y colaborar en proyectos.

En el epígrafe anterior hemos utilizado Git para crear un repositorio y registrar cambios de forma local:

Equipo local
└── repositorio Git

Con GitHub podemos mantener también una copia del repositorio en un servidor remoto:

Equipo local                 GitHub
┌─────────────────┐         ┌─────────────────┐
│ Repositorio Git │ ←─────→ │ Repositorio Git │
│      local      │         │     remoto      │
└─────────────────┘         └─────────────────┘

Git continuará gestionando el control de versiones. GitHub proporcionará el alojamiento remoto y las herramientas de colaboración.

Cuenta de GitHub

Para utilizar GitHub necesitamos disponer de una cuenta:

GitHub

La documentación oficial está disponible en:

GitHub Docs

Durante el módulo utilizaremos repositorios pertenecientes a las organizaciones de GitHub creadas para las diferentes unidades y prácticas.

Repositorios locales y remotos

Un repositorio local se encuentra almacenado en nuestro equipo.

Un repositorio remoto se encuentra alojado en otro sistema al que podemos acceder a través de una red.

Git permite relacionar ambos repositorios y transferir cambios entre ellos.

Para enviar los commits locales al repositorio remoto utilizamos git push:

Repositorio local
       ↓
    git push
       ↓
Repositorio remoto

Para obtener e incorporar los cambios remotos utilizamos git fetch y git pull:

Repositorio remoto
       ↓
    git fetch
       ↓
Revisar cambios
       ↓
    git pull
       ↓
Repositorio local actualizado

Esta separación permite trabajar localmente y sincronizar posteriormente el trabajo con GitHub.

Crear un repositorio en GitHub

Podemos crear un nuevo repositorio desde GitHub mediante la opción:

New repository

Al crearlo debemos indicar información como:

• Propietario del repositorio.
• Nombre.
• Descripción.
• Visibilidad.

La visibilidad puede ser:

• Public, si el repositorio puede ser consultado públicamente.
• Private, si el acceso está restringido a los usuarios autorizados.

TIP

Durante las prácticas deberemos respetar siempre el nombre, propietario y visibilidad del repositorio indicados en el enunciado.

Conectar un repositorio local con GitHub

Si ya tenemos un repositorio Git en nuestro equipo, podemos conectarlo con el repositorio creado en GitHub.

Git identifica los repositorios remotos mediante nombres.

Por convenio, el repositorio remoto principal suele denominarse:

origin

Podemos añadirlo mediante:

git remote add origin URL_REPOSITORY

Por ejemplo:

git remote add origin git@github.com:organization/technical-documentation.git

Podemos comprobar los repositorios remotos configurados mediante:

git remote -v

origin

origin no es una palabra especial de Git que identifique obligatoriamente a GitHub.

Es simplemente el nombre convencional que suele utilizarse para identificar el repositorio remoto principal.

Autenticación

Para enviar cambios a GitHub debemos identificarnos ante la plataforma.

GitHub permite utilizar diferentes mecanismos de autenticación. Durante el módulo utilizaremos SSH para trabajar con los repositorios desde la terminal.

La comunicación se realizará utilizando direcciones como:

git@github.com:organization/repository.git

Para ello será necesario disponer de una clave SSH configurada en nuestro equipo y asociar su clave pública con nuestra cuenta de GitHub.

Podemos comprobar la conexión mediante:

ssh -T git@github.com

Claves privadas

Una clave SSH está formada por una parte pública y una parte privada.

La clave privada nunca debe compartirse, publicarse ni incluirse en un repositorio.

Enviar cambios

El comando git push permite enviar al repositorio remoto los commits realizados localmente.

Antes del primer envío podemos comprobar nuestra rama actual mediante:

git branch --show-current

Si trabajamos con la rama main, podemos realizar el primer envío mediante:

git push -u origin main

La opción -u establece la relación entre la rama local main y la rama correspondiente del repositorio remoto.

A partir de ese momento normalmente será suficiente utilizar:

git push

El flujo será:

Modificar archivos
       ↓
    git add
       ↓
   git commit
       ↓
    git push
       ↓
     GitHub

TIP

git push no envía simplemente los archivos que acabamos de modificar.

Los cambios deben haberse registrado previamente mediante uno o varios commits.

Descargar un repositorio

Cuando un repositorio ya existe en GitHub y queremos obtener una copia completa en nuestro equipo podemos utilizar:

git clone URL_REPOSITORY

Por ejemplo:

git clone git@github.com:organization/technical-documentation.git

Git descargará el repositorio, creará el directorio correspondiente y configurará automáticamente el remoto origin.

Después podemos acceder al proyecto:

cd technical-documentation

y comprobar su configuración:

git remote -v

Obtener cambios

Cuando trabajamos desde diferentes equipos o colaboramos con otras personas, el repositorio remoto puede contener commits que todavía no tenemos incorporados en nuestra rama local.

Antes de comenzar a trabajar, es recomendable comprobar si existen nuevos cambios y revisarlos antes de incorporarlos.

Comprobar el estado del repositorio

El comando git status permite comprobar el estado actual de nuestro repositorio:

git status

Entre otras cosas, podemos identificar:

• La rama en la que estamos trabajando.
• Los archivos modificados que todavía no hemos registrado mediante un commit.
• Los archivos preparados para el próximo commit.
• Si nuestra rama está adelantada o retrasada respecto a su referencia remota, según la última información disponible.

Obtener información del remoto

El comando git fetch obtiene los nuevos commits y actualiza las referencias remotas sin modificar nuestra rama local ni los archivos de trabajo:

git fetch

Después podemos volver a comprobar el estado:

git status

Si nuestra rama local está retrasada respecto a la remota, Git nos informará de que existen commits pendientes de incorporar.

git fetch

git fetch actualiza la información que tenemos del repositorio remoto, pero no incorpora automáticamente sus cambios a nuestra rama local.

Esto nos permite revisar los cambios antes de integrarlos.

Revisar los cambios

Para consultar los commits y comparar las diferencias entre la rama local y la remota podemos utilizar comandos como:

git log HEAD..origin/main --oneline
git diff HEAD origin/main

• git log permite consultar el historial de commits.
• git diff permite comparar los cambios entre archivos, commits o ramas.

En estos ejemplos, origin/main representa la referencia local a la rama main del repositorio remoto denominado origin.

Visual Studio Code

Durante el módulo utilizaremos principalmente Visual Studio Code y la extensión Git Graph para consultar el historial de commits y comparar cambios de forma gráfica.

Aunque es importante conocer git log y git diff, estas operaciones suelen resultar más cómodas desde el entorno gráfico.

En cambio, utilizaremos habitualmente git status desde la terminal para comprobar el estado del repositorio.

Incorporar los cambios

Una vez revisados los cambios remotos, podemos incorporarlos mediante:

git pull

Este comando obtiene los cambios del repositorio remoto y trata de integrarlos en la rama local.

Diferencia entre fetch y pull

• git fetch obtiene los nuevos commits y actualiza las referencias remotas, pero no modifica nuestra rama local ni los archivos de trabajo.
• git pull obtiene los cambios del repositorio remoto y trata de integrarlos en la rama local.

Utilizar primero git fetch permite revisar los cambios antes de incorporarlos mediante git pull.

Antes de ejecutar git pull, es recomendable comprobar que no tenemos modificaciones locales pendientes de registrar.

Si existen commits divergentes o cambios incompatibles, pueden ser necesarias operaciones adicionales para integrar los cambios.

Flujo habitual de trabajo

Una vez conectado el repositorio local con GitHub, el flujo habitual será:

1. Comprobar el estado del repositorio local.
2. Obtener la información más reciente del repositorio remoto.
3. Comprobar si existen cambios remotos pendientes.
4. Revisar los cambios mediante Visual Studio Code.
5. Incorporar los cambios remotos, si existen.
6. Modificar los archivos.
7. Comprobar los cambios realizados.
8. Preparar los cambios.
9. Crear un commit.
10. Enviar los commits a GitHub.

Antes de comenzar a trabajar:

git status
git fetch
git status

Si existen cambios remotos pendientes, los revisamos mediante Visual Studio Code y posteriormente los incorporamos:

git pull

Después de modificar la documentación:

git status
git add .
git commit -m "Update installation guide"
git push

El flujo completo será:

git status
    ↓
git fetch
    ↓
git status
    ↓
Revisar cambios en VS Code
    ↓
git pull (si hay cambios pendientes)
    ↓
Modificar archivos
    ↓
git status
    ↓
git add
    ↓
git commit
    ↓
git push

Después del push, podemos acceder al repositorio desde el navegador y comprobar que el nuevo commit aparece también en GitHub.

README.md en GitHub

Cuando un repositorio contiene un archivo README.md, GitHub muestra automáticamente su contenido en la página principal del repositorio.

Por ejemplo:

technical-documentation/
├── images/
├── installation.md
└── README.md

Esto convierte al README.md en un lugar adecuado para proporcionar una presentación general del proyecto y facilitar el acceso al resto de la documentación.

Historial de cambios

GitHub permite consultar desde el navegador los commits almacenados en el repositorio.

Podemos utilizar esta información para:

• Consultar el historial del proyecto.
• Identificar quién realizó un cambio.
• Comprobar cuándo se realizó.
• Consultar los archivos modificados.
• Comparar diferentes cambios.

El historial que observamos en GitHub procede de los commits creados mediante Git y enviados posteriormente al repositorio remoto.

También podemos consultar el historial de nuestro repositorio local desde Visual Studio Code mediante la extensión Git Graph.

Colaboración

Una de las principales utilidades de GitHub es permitir que varias personas trabajen sobre un mismo proyecto.

GitHub incorpora herramientas como:

• Repositorios compartidos.
• Ramas.
• Issues.
• Pull requests.
• Revisión de cambios.
• Gestión de permisos.

En esta unidad utilizaremos principalmente GitHub para alojar y compartir nuestros repositorios de documentación.

Estas herramientas permiten desarrollar flujos de trabajo más complejos cuando varias personas participan en un mismo proyecto.

Git y GitHub

Conviene mantener clara la diferencia entre ambas herramientas:

Git	GitHub
Sistema de control de versiones	Plataforma de alojamiento y colaboración
Se ejecuta en nuestro equipo	Servicio accesible a través de Internet
Gestiona commits e historial	Aloja repositorios Git
Puede utilizarse sin GitHub	Utiliza Git como base para los repositorios

Por tanto, podemos utilizar Git sin GitHub, y también existen otras plataformas capaces de alojar repositorios Git.

Flujo completo

El flujo que hemos construido hasta este momento es:

Archivos
   ↓
Visual Studio Code
   ↓
Markdown
   ↓
Git
   ↓
GitHub

Un ejemplo completo sería:

mkdir technical-documentation
cd technical-documentation

git init -b main

touch README.md
code .

Después de crear la documentación:

git status
git add README.md
git commit -m "Add initial documentation"

Conectamos el repositorio con GitHub, suponiendo que hemos creado previamente un repositorio remoto vacío:

git remote add origin git@github.com:organization/technical-documentation.git
git push -u origin main

A partir de entonces, antes de realizar nuevos cambios:

git status
git fetch
git status

Si existen cambios remotos pendientes, los revisamos mediante Visual Studio Code y los incorporamos:

git pull

Después de modificar la documentación:

git status
git add .
git commit -m "Update documentation"
git push

De esta forma disponemos de la documentación tanto en nuestro equipo como en un repositorio remoto alojado en GitHub.

En el siguiente epígrafe utilizaremos GitHub Pages para publicar esta documentación en Internet.