Sistemas informáticos

Appearance

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:

text
Equipo local
└── repositorio Git

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

text
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.

Por ejemplo:

text
Repositorio local
      ↓
    push
      ↓
Repositorio remoto

y en sentido contrario:

text
Repositorio remoto
      ↓
    pull
      ↓
Repositorio local

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:

text
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:

text
origin

Podemos añadirlo mediante:

bash
git remote add origin URL_REPOSITORY

Por ejemplo:

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

Podemos comprobar los repositorios remotos configurados mediante:

bash
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:

text
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:

bash
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:

bash
git branch --show-current

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

bash
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:

bash
git push

El flujo será:

text
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:

bash
git clone URL_REPOSITORY

Por ejemplo:

bash
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:

bash
cd technical-documentation

y comprobar su configuración:

bash
git remote -v

Obtener cambios ​

Si el repositorio remoto contiene cambios que todavía no tenemos localmente, podemos obtenerlos mediante:

bash
git pull

Por ejemplo, si hemos trabajado desde otro equipo o algún colaborador ha actualizado el repositorio, git pull permite incorporar esos cambios a nuestra copia local.

De forma simplificada:

text
GitHub
   ↓
git pull
   ↓
Repositorio local

Antes de comenzar a trabajar sobre un repositorio compartido es recomendable comprobar que nuestra copia local está actualizada.

Flujo habitual de trabajo ​

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

  1. Obtener los últimos cambios del repositorio remoto.
  2. Modificar los archivos.
  3. Comprobar los cambios realizados.
  4. Preparar los cambios.
  5. Crear un commit.
  6. Enviar los commits a GitHub.

Por ejemplo:

bash
git pull
git status
git diff
git add .
git commit -m "Update installation guide"
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:

text
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.

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:

GitGitHub
Sistema de control de versionesPlataforma de alojamiento y colaboración
Se ejecuta en nuestro equipoServicio accesible a través de Internet
Gestiona commits e historialAloja repositorios Git
Puede utilizarse sin GitHubUtiliza 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:

text
Archivos
   ↓
Visual Studio Code
   ↓
Markdown
   ↓
Git
   ↓
GitHub

Un ejemplo completo sería:

bash
mkdir technical-documentation
cd technical-documentation

git init

touch README.md
code .

Después de crear la documentación:

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

Conectamos el repositorio con GitHub:

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

A partir de entonces, después de realizar nuevos cambios:

bash
git pull
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.