Introducción
Este artículo es una guía paso a paso para ayudar a principiantes a configurar Git en un nuevo proyecto y sincronizarlo con GitHub. Además, aprenderás a usar claves SSH para evitar la necesidad de ingresar contraseñas repetidamente. Al final, también abordaremos cómo crear tags y disponibilizar releases para tu proyecto.
Prerrequisitos
Crear una Cuenta en GitHub y Configurar un Nuevo Repositorio
Antes de comenzar, necesitarás tener una cuenta en GitHub y crear un repositorio para almacenar tu proyecto. Este proceso es intuitivo y cuenta con asistencia directa de la propia plataforma durante las etapas. Asegúrate de seguir las indicaciones en GitHub para completar esta configuración inicial.
Entorno de Desarrollo
Los comandos presentados en este artículo fueron probados en Linux Slackware 15.0, utilizando las herramientas nativas Git (versión 2.46.3) y OpenSSH (versión 9.9p2). Los comandos son genéricos y deberían funcionar en cualquier distribución Linux que tenga Git y SSH instalados.
Iniciando Git en el Proyecto Local
Paso 1: Configurar Git para Usar main Como Branch Predeterminada
Muchas plataformas modernas (como GitHub, GitLab y Bitbucket) adoptan el nombre main como branch predeterminada. Para garantizar que nuevos repositorios usen automáticamente main como branch principal, es necesario ajustar la configuración global de Git. Ejecuta el siguiente comando:
$ bash
git config --global init.defaultBranch main
Con esta configuración, el comando git init creará automáticamente la branch main, eliminando la necesidad de renombrarla manualmente.
Paso 2: Inicializando el Repositorio
Considerando un proyecto denominado telazul, a continuación se presentan los pasos necesarios para configurar Git en este directorio y preparar el proyecto para sincronización con GitHub.
$ bash
# Entra al directorio del proyecto cd telazul/ # Inicializa el repositorio Git git init
El comando git init se usa solo una vez para crear la estructura necesaria para el repositorio. Para verificar el nombre de la branch actual y renombrarla si es necesario, usa los siguientes comandos:
$ bash
# Verifica el nombre de la branch actual git branch # Renombra la branch master a main git branch -m master main
Paso 3: Agregando Archivos al Repositorio Local
Agrega todos los archivos y directorios al repositorio y guarda los cambios con un mensaje informativo:
$ bash
# Agrega todos los archivos de la carpeta actual recursivamente git add . # Guarda los cambios permanentemente con un mensaje descriptivo git commit -m "Commit inicial: agregando archivos del proyecto"
El comando git add . agrega todos los archivos modificados o nuevos al índice, mientras que git commit crea una instantánea del estado actual de los archivos, guardando los cambios permanentemente. Como es posible recuperar el estado exacto de este commit en el futuro, el mensaje asociado debe ser claro y descriptivo para facilitar la identificación de los cambios realizados.
Los pasos anteriores configuran Git en el proyecto local. Son independientes de la integración con GitHub y pueden usarse en cualquier flujo de trabajo de Git.
Configurando Acceso SSH a GitHub
El proyecto se transferirá usando SSH, un protocolo seguro y práctico para transferir archivos por internet. Para ello, es necesario configurar claves SSH que funcionarán como credenciales, permitiendo el inicio de sesión en GitHub sin necesidad de ingresar una contraseña.
$ bash
# Crea las claves usando el algoritmo ed25519
ssh-keygen -t ed25519
Cuando se te pregunte, presiona para mantener la ubicación predeterminada ~/.ssh/ y para usar una contraseña en blanco. Si ya tienes claves SSH compatibles con GitHub (como id_rsa o id_ed25519), no es necesario crear nuevas claves.
Agregando la Clave Pública a GitHub
Para transferir la clave pública entre computadoras Linux, puedes usar el comando ssh-copy-id. Sin embargo, en GitHub, es necesario copiar y pegar la clave manualmente en la interfaz gráfica de la plataforma.
La clave pública está almacenada en el archivo que termina con .pub. Para mostrar su contenido, usa el siguiente comando (reemplaza tu-usuario por el nombre de tu usuario en el sistema):
$ bash
cat /home/tu-usuario/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEDbDtQNhBvGd292FgKDRgqhiXGiLHo32ZYXCSS017d5 tu-usuario@nombre-del-host
Copia la línea completa que comienza con ssh-ed25519 (clave pública) y:
- Accede a GitHub y en el menú con tu avatar en la esquina superior derecha.
- Navega hasta > .
- También puedes usar el enlace directo: https://github.com/settings/keys.
- Haz clic en ,
- Completa el campo Title con un nombre descriptivo para la clave (ej.: "Clave SSH de mi notebook").
- Pega la clave pública en el campo Key.
- Haz clic en para guardar.
Después de la configuración, la clave aparecerá listada en la página de claves SSH, como se ilustra a continuación:
Subiendo el Proyecto a GitHub
Para conectar el repositorio local al repositorio remoto en GitHub, usa el siguiente comando. Este agrega el alias origin al repositorio remoto, permitiendo referenciarlo fácilmente en operaciones futuras.
$ bash
git remote add origin git@github.com:tu-usuario/tu-repositorio.git
Asegúrate de ejecutar el comando anterior dentro de la carpeta del proyecto y reemplaza tu-usuario por tu nombre de usuario en GitHub y tu-repositorio por el nombre del repositorio creado en la plataforma.
Ahora, envía el proyecto al repositorio remoto con el siguiente comando:
$ bash
git push -u -f origin main
- El parámetro -u (o --set-upstream) define origin como la referencia predeterminada para la branch main. Después de esta configuración, podrás usar los comandos git push y git pull sin necesidad de especificar el repositorio remoto o la branch.
- El parámetro -f (o --force) fuerza la actualización del repositorio remoto, sobrescribiendo cualquier contenido existente. Este parámetro es útil al iniciar un nuevo proyecto cuando el repositorio remoto contiene archivos predeterminados (como LICENSE o README.md) que impiden el push inicial.
Sincronizando Cambios del Repositorio Remoto
Entra en el sitio de GitHub y crea el archivo README con algún contenido. Para sincronizar estos cambios en el repositorio remoto con el repositorio local, ejecuta el siguiente comando desde la carpeta del proyecto:
$ bash
git pull
El comando git pull trae todos los commits más recientes de la branch remota y los aplica a la branch local.
Como se mencionó anteriormente, al subir el proyecto con el comando git push usando el parámetro -u, el repositorio en GitHub se define como referencia predeterminada. Esto elimina la necesidad de especificar el nombre del repositorio remoto (origin) en comandos posteriores.
Después de ejecutar el comando, verifica que el archivo README creado remotamente ahora está presente en la carpeta local del proyecto.
Actualizando Archivos Localmente
Edita el archivo README en el repositorio local, agregando una nueva línea. Luego, registra los cambios y envíalos al repositorio remoto con los siguientes comandos:
$ bash
git commit -a -m "Actualización del archivo README" git push
El parámetro -a prepara automáticamente todos los archivos modificados o eliminados en el repositorio local. Sin embargo, no incluye nuevos archivos (archivos que aún no han sido rastreados por Git). Para incluir nuevos archivos, usa el comando git add.
El parámetro -m permite agregar un mensaje descriptivo al commit.
El comando git push actualiza el repositorio remoto en GitHub con los cambios recientes realizados en la carpeta local del proyecto.
Versionamiento Semántico
Antes de entrar en el tema de tags y releases, es importante entender brevemente la numeración utilizada en las versiones de software. El Versionamiento Semántico (o SemVer) es una convención ampliamente adoptada para nombrar versiones de software, facilitando la comunicación sobre cambios y garantizando compatibilidad.
Sigue el formato:
MAYOR.MENOR.PARCHE
- MAYOR: Incrementado cuando hay cambios incompatibles con versiones anteriores (ej.: alteraciones que rompen APIs o funcionalidades).
- MENOR: Incrementado cuando se agregan funcionalidades compatibles (sin romper el funcionamiento actual).
- PARCHE: Incrementado para correcciones de errores o pequeñas mejoras que no alteran funcionalidades existentes.
Ejemplos
- 1.0.0: Primera versión estable del software.
- 1.1.0: Adición de nuevas funcionalidades sin romper la compatibilidad.
- 1.1.1: Corrección de errores en la versión 1.1.0.
- 2.0.0: Cambios incompatibles con la versión 1.x.x.
Es una práctica recomendada para proyectos que necesitan comunicar claramente el estado de desarrollo y los cambios introducidos en cada versión.
Nombrando Versiones con Tags
Una tag es una referencia estática que apunta a un commit específico en el historial de Git. A diferencia de los branches, que pueden avanzar y cambiar con el tiempo, las tags son fijas y no cambian después de crearse. Esto las hace ideales para marcar eventos importantes, como lanzamientos de versiones que pueden ser disponibles para que los usuarios las descarguen.
$ bash
git tag v1.0.0
Este comando crea una tag llamada v1.0.0, generando una versión definitiva del proyecto que contiene todos los archivos y directorios en el estado en que estaban en el momento del último commit ejecutado.
El prefijo v (de "versión") es una convención adoptada para identificar tags de versión, facilitando su distinción en el historial de Git, especialmente entre otras marcas (ej.: beta-test).
Para nombrar un commit específico, diferente al actual, con una tag usa:
$ bash
git tag nombre-de-la-tag hash-del-commit
Para descubrir el hash-del-commit consulta este tema.
Los comandos anteriores crean las llamadas tags simples (o ligeras). Otra opción son las tags anotadas, que son más detalladas e incluyen metadatos, como mensaje, autor y fecha. Se recomiendan para marcar versiones importantes.
Para crear una tag anotada, usa el parámetro -a:
$ bash
git tag -a v1.0 -m "Versión 1.0 estable"
Otros comandos útiles para gestionar tags:
$ bash
# Lista todas las tags git tag # Lista todas las tags y sus commits git log --oneline --decorate # Muestra detalles sobre una tag específica git show nombre-de-la-tag
Enviando Tags al Repositorio Remoto
Por defecto, las tags no se envían automáticamente al repositorio remoto al usar el comando git push. Para enviar tags al repositorio remoto, usa los siguientes comandos:
$ bash
# Envía una tag específica git push origin nombre-de-la-tag # Envía todas las tags de una vez git push origin --tags
Ejemplo Práctico
Supón que acabas de concluir la versión 1.0 de tu proyecto. Puedes marcar este momento con una tag anotada y enviarla al repositorio remoto siguiendo estos pasos:
$ bash
# Crea la tag localmente git tag -a v1.0 -m "Versión 1.0 estable" # Envía la tag al repositorio remoto git push origin v1.0
Eliminando Tags
Las tags en Git son referencias inmutables por diseño, lo que significa que, una vez creadas, siempre apuntan al commit al que fueron asignadas. Sin embargo, es posible eliminarlas.
Para eliminar una tag local:
$ bash
git tag -d nombre-de-la-tag
Para eliminar una tag remota:
$ bash
git push origin --delete nombre-de-la-tag
Este comando eliminará la tag en GitHub.
Actualizando Tags
Las tags en Git no pueden actualizarse directamente. Sin embargo, es posible simular una actualización eliminando la tag existente y creando una nueva con el mismo nombre. Para ello, sigue los pasos a continuación:
$ bash
# Elimina la tag local git tag -d nombre-de-la-tag # Elimina la tag remota git push origin --delete nombre-de-la-tag # Crea la nueva tag con el mismo nombre git tag -a nombre-de-la-tag -m "Nuevo mensaje de la tag" # Envía la nueva tag al repositorio remoto git push origin nombre-de-la-tag
¡Atención! Buenas Prácticas al "Actualizar" Tags
Aunque técnicamente es posible eliminar y recrear tags con el mismo nombre, esta práctica puede causar confusión, especialmente si la tag original ya está siendo usada por otras personas. Cambiar una tag después de haber sido compartida puede llevar a inconsistencias en el historial del proyecto.
Creando una Nueva Release en GitHub
Comienza creando una tag local para indicar la versión de tu proyecto y envíala al repositorio remoto en GitHub:
$ bash
# Crea la tag localmente git tag -a v1.0.0 -m "Versión 1.0.0 estable" # Envía la tag al repositorio remoto git push origin v1.0.0
En GitHub:
- Accede a la página de releases.
- https://github.com/tu-usuario/tu-repositorio/releases
- Haz clic en .
- Completa los detalles de la release:
- : Selecciona la tag que creaste (ej: v1.0.0) o crea una nueva directamente en esta pantalla. En este ejemplo, la tag se está creando localmente y se transfiere al repositorio remoto, sin embargo, el proceso inverso también es válido.
- : Proporciona un título descriptivo para la release (por ejemplo, v1.0.0 - Versión Estable).
- : Agrega una descripción detallada de la release. Incluye información como: qué se agregó, corrigió o alteró, enlaces a documentación, recursos relacionados, etc.
- : Marca esta opción si la versión es beta o experimental. De lo contrario, déjala desmarcada.
- Publica haciendo clic en .
Después de publicar la release, GitHub disponibiliza automáticamente los archivos asociados al commit marcado por la tag. Puedes descargarlos como un archivo .zip o .tar.gz.
Conclusión
Este artículo fue escrito para ser una guía práctica, en la que las personas puedan consultar los pasos necesarios para crear sus primeros proyectos y disponibilizarlos para descarga en GitHub. Si lograste configurar tu repositorio, crear tags, releases y compartir tu trabajo con el mundo, cumplió su propósito.
Continúa explorando Git y GitHub, y aprovecha todas las posibilidades que estas herramientas ofrecen para organizar, compartir y colaborar en tus proyectos.
Referencias
- https://docs.github.com/en/get-started/start-your-journey/uploading-a-project-to-github
- https://stackoverflow.com/questions/12799719/how-to-upload-a-project-to-github
- https://www.digitalocean.com/community/tutorials/how-to-push-an-existing-project-to-github
