Categorías
España Informática Nacional Universitario

GitHub

A la hora de realizar proyectos es recomendable gestionarlos con algún sistema de control de versiones. Git es uno de estos sistemas y posiblemente el repositorio más popular con servicios gratuitos de este tipo es GitHub. Aquí explicamos algunos conceptos importantes para trabajar con estas tecnologías.

Git

Como requisito para poder trabajar con GitHub es necesario instalar Git en nuestro sistema. Por ejemplo la última versión de Git for Windows que puedas encontrar en la web de Git.

Al instalarlo hay muchas opciones a tener en cuenta, pero la más importante si vas a usar repositorios de Azure y cosas así, es usar Git Credential Manager, para gestionar las credenciales bien y poder conectar por HTTPS con el repositorio.

Aunque es posible trabajar mediante consola de comandos (o con un intérprete avanzado de comandos, como el shell Bash), lo más habitual -al menos para las tareas comunes del día a día- es utilizar alguna aplicación basada en ventanas para trabajar con el repositorio, como GitHub Desktop o GitKraken.

Las operaciones típicas para trabajar con estos repositorios se llaman push (llevar código local a un repositorio aparte) y pull (fetch + merge, es decir, traer código de un repositorio aparte y además “mezclarlo”, automáticamente si es posible, con mi código local).

Git LFS

Cuando se trabaja con proyectos grandes y complejos, como los videojuegos, es normal que dentro del proyectos se incluyan muchos y muy grandes ficheros binarios. En un principio Git no estaba pensado para llevar el control de versiones de ese tipo de ficheros, y para ello se creó una extensión llamada Git LFS (Large File Storage). Instalando cierto software en nuestra máquina “cliente” y aprovechando un espacio que GitHub ofrece en la máquina “servidor”, es posible trabajar más cómodamente con proyectos que incluyen ficheros binarios. Para funcionar en modo LFS, es necesario incluir un fichero .gitattributes donde se indique qué ficheros del proyecto son los que deben tratarse con este nuevo sistema.

En Unreal Engine es habitual que todos los ficheros .uasset y .umap se traten como ficheros binarios potencialmente grandes (es decir, mediante LFS y además con la posibilidad de bloquearlos para impedir que varios miembros del equipo hagan cambios a la vez). Gracias a la tecnología “One File Per Actor” de Unreal Engine 5 es cierto que ahora los .umap no tienen porque ser tan pesados… pero se les sigue tratando con LFS.

Sin embargo la capacidad de almacenamiento “Git LFS Data” que GitHub ofrece de forma gratuita no es muy grande: tan sólo 1 GB para todos los repositorios de una cuenta u organización, con un límite de transferencia mensual también de 1 GB. Además aunque es técnicamente posible borrar esos ficheros, la única forma de que dejen de estar en GitHub a día de hoy es borrando el repositorio entero y creando otro nuevo. Por eso la recomendación es que si hay grandes paquetes de contenido de terceros (StarterContent de UE, Characters de UE5, Megascans de Quixel, paquetes de escenarios y objetos descargados de tiendas digitales, etc.) sobre los que no vamos a hacer modificaciones, es mejor no manejarlos con el sistema LFS o incluso ignorarlos por completo (es decir, no guardarlos en el repositorio sino en otro sistema de almacenamiento, como el propio Google Drive).

Para ver el espacio que tenemos ocupado con este sistema hay que acceder a los ajustes o Settings de la cuenta u organización, y mirar dentro de Billing and plans en el apartado Git LFS Data / Storage. Si nos quedamos sin espacio (a menudo por no usar bien los ficheros .gitignore y gitattributes) actualmente GitHub no ofrece más soluciones que pagar a cambio de más espacio o directamente BORRAR los repositorios involucrados, perdiendo todas las versiones (commits, ramas, etc.) y demás metainformación que hubiese en ellos. Toca descargar todo el contenido del repositorio, borrarlo y recrearlo después, para volver a subir el contenido en un único commit (asegurándonos de que tenemos .gitignore y .gitattributes bien configurados para no subir ningún fichero prescindible, y gestionar con el sistema LFS exclusivamente los ficheros binarios sobre los que vamos a trabajar intensivamente).

Algo que todavía no se usa mucho es el sistema de bloqueo (locking) en Git LFS, aunque en otros sistemas como Perforce es muy habitual. Esto permite “bloquear” ciertos ficheros binarios para que ningún otro usuario los pueda tocar mientras que nosotros los estamos modificando. Esto tiene mucho sentido porque hacer el “merge” entre versiones distintas de un fichero binario suele ser impracticable…

GitHub

Siendo estudiante universitario es posible obtener una cuenta GitHub Pro para poder, entre otras cosas, crear organizaciones dentro de GitHub (por ejemplo para los grupos de prácticas). De normal, GitHub Free permite crear repositorio ilimitados (con características restringidas si son privados), pero con añadir vuestra cuenta de dominio UCM (nombre@ucm.es) a vuestro usuario de GitHub ya es suficiente para que la cuenta pase a considerarse GitHub Pro.

Para por ejemplo dar acceso a otros a que vean los “insights” de un repositorio que está dentro de una organización, o bien el proyecto debe ser público o debe contarse con una cuenta GitHub Teams (no es suficiente con una GitHub Pro). De todas formas, tranquilos: para que el profesor pueda ver la cantidad de commits realizados y quienes son los alumnos que los han hecho, no es necesario consultar los “insights” y es suficiente con tener la mencionada cuenta GitHub Pro.

Es crucial no subir al repositorio NADA que no sea imprescindible porque lo podamos regenerar o guardar en otro sitio. De ahí la importancia de incluir un fichero .gitignore donde se indiquen qué ficheros del proyecto que están en nuestro disco duro deben subirse a GitHub.

Cada dos años GitHub vuelve a solicitar una foto del carnet de estudiante o profesor, y por ejemplo, por ser profesor, es posible hacer “upgrade” a las organizaciones a GitHub Teams, y usar GitHub Classroom para las prácticas y demás.

Bifurcaciones y duplicados

A la hora de replicar un repositorio, por ejemplo el punto de partida de una práctica que nos comparte un profesor, lo habitual es bifurcarlo (crear un fork), lo que nos permite mantener conectado nuestro repositorio con el original que tomamos como base.

Sin embargo si el repositorio base es público, GitHub no permite crear un fork privado, y por eso nos vemos obligados a duplicar el repositorio de una manera especial:

  1. Crear un clon “desnudo” del repositorio que queremos duplicar en tu ordenador, usando el comando git clone –bare … .
  2. Crea un repositorio privado en GitHub con el mismo nombre.
  3. Sube el clon de tu ordenador en modo “espejo” al repositorio privado, usando el comando git push –mirror … .
  4. Borra el clon de tu ordenador, porque ya no lo necesitas.
  5. Clona el repositorio privado de GitHub en tu ordenador, que es donde vas a trabajar.
  6. Añade el repositorio que duplicamos como un repositorio remoto (upstream) del que potencialmente poder traer futuros cambios al nuestro (origin), usando el comando git remote add upstream … . Lo normal es no tener permiso para subir código a este repositorio, por lo que se recomienda desactivar esa posibilidad con git remote set-url –push upstream DISABLE .

Si haces este duplicado los push serán en tu repositorio (origin) y si quieres traer cambios que se hayan hecho en el repositorio base -por ejemplo en la rama main– se traerán con git fech upstream y se pondrán “encima” de tu código con git rebase upstream/main .

Markdown

Una potente herramienta para documentar que incluye GitHub es Markdown. Se trata de un lenguaje muy sencillo y cómodo que permite crear páginas web a través de un simple “texto plano” que incluye ciertas marcas (como asteriscos, corchetes, etc.) puestas de una forma determinada.

También es posible crear diagramas de todo tipo, incluidos UML, usando extensiones a Markdown específicas para ello, como es el caso de Mermaid.

Issues & Projects

Para gestión de tareas existe la herramienta GitHub Issues, que permite hacer un seguimiento de cualquier error o problema en el proyecto.

Entre todo lo que ofrece GitHub Issues está Projects, un panel que permite representar las tareas pendientes al estilo Kanban.

Más información

Para complementar es recomendable consultar otros documentos.

Esta página está licenciada bajo CC BY-NC-SA 4.0 por Laboratorios Narratech.