Guía Git & GitHub

Guía didáctica del ciclo de vida de un programa

Desde el IDE hasta GitHub: comandos esenciales, flujo de trabajo y buenas prácticas.

Autor: Francesc Fosas (con asistencia de IA)

Edición: Guía Git + GitHub | 2026

Licencia libre: puedes usar, copiar y distribuir este documento libremente citando al autor.

Contenido de esta guía

Instalación y primeros pasos en la Terminal
¿Qué es Git y para qué sirve?
El ciclo de vida de un archivo
Configuración inicial
Del IDE a Git: crear un repositorio local
Comandos del día a día
Ramas (branches): trabajar en paralelo
De Git a GitHub: el repositorio remoto
Flujo de trabajo completo
Conflictos de merge: cuando dos ramas chocan
Deshacer cosas y Diagnóstico: cuando algo sale mal
Buenas prácticas y Seguridad
Chuleta rápida de comandos

1. Instalación y primeros pasos en la Terminal

Paso previo: Instalar Git

Tu ordenador no reconocerá los comandos de Git si no instalas el software base primero.

Windows: Descarga el instalador desde git-scm.com y ejecútalo (puedes dar a "Siguiente" en todo). ¡Importante! Una vez instalado, busca en tu ordenador el programa llamado Git Bash y ábrelo. No utilices el CMD normal ni PowerShell, ya que Git Bash simula un entorno Linux mucho más amigable para Git.
macOS: Abre la terminal y escribe git --version. Si no está instalado, el sistema te preguntará automáticamente si deseas instalar las herramientas de línea de comandos. Acéptalo.
Linux (Ubuntu/Debian): Abre tu terminal y ejecuta el comando sudo apt install git.
Linux (openSUSE): Abre tu terminal y ejecuta el comando sudo zypper install git.
Linux (Fedora/RHEL): Abre tu terminal y ejecuta el comando sudo dnf install git.

La Terminal (Tu entorno de trabajo)

Antes de escribir comandos de Git, debes asegurarte de que tu terminal está apuntando a la carpeta correcta de tu proyecto. El error número uno de los estudiantes es ejecutar Git en la carpeta equivocada (como el Escritorio). Usa estos comandos (válidos para Mac, Linux y Git Bash en Windows):

Saber dónde estás: Escribe pwd (Print Working Directory) y presiona Enter.
Ver qué hay en la carpeta: Escribe ls.
Ver TODO (incluido lo oculto): Escribe ls -a.
Entrar a tu proyecto: Escribe cd nombre-de-tu-carpeta (Ej: cd mi_proyecto_web).

2. ¿Qué es Git y para qué sirve?

Git es un sistema de control de versiones distribuido que funciona en tu ordenador local. Imagínalo como un sistema de puntos de guardado para tu código. Registra cada cambio en tus archivos como un historial permanente. Si algo se rompe, puedes volver a cualquier punto anterior.

GitHub es la plataforma web que aloja repositorios Git en la nube. Es el equivalente a un disco virtual, pero diseñado específicamente para código, permitiendo colaborar, revisar el trabajo de otros y mantener copias de seguridad.

Situación	Sin Git	Con Git
Guardar cambios	`Ctrl+S` (sobrescribe y pierdes lo anterior)	`git commit`: punto de guardado inmutable
Historial	Carpetas: "final_v2", "final_BUENO"...	`git log`: historial automático y ordenado
Colaborar	Enviar código por email o ZIP	`git push`/`pull` en GitHub
Revertir un error	Empezar de cero o buscar un backup	`git revert`: vuelve atrás en segundos

3. El ciclo de vida de un archivo

💻

Working Dir.

Tu mesa de trabajo

git add

📦

Staging Area

Caja abierta

git commit

🏷️

Local Repo.

Caja sellada

git push

☁️

Remoto

Almacén nube

Es común preguntarse por qué son necesarios dos pasos (add y luego commit) para guardar un archivo. Para entenderlo de forma sencilla, podemos pensar en el proceso de preparar una caja de envío.

Zona oficial	Funcionamiento práctico	Qué significa técnicamente
Working Directory	Tu mesa de trabajo.	Tu disco duro. Editas código libremente. Git sabe que cambiaste cosas, pero no está haciendo nada con ellas aún.
Staging Area	Meter cosas en una caja abierta.	(`git add`). Preparas exactamente qué archivos van a guardarse. Puedes incluir algunos archivos y dejar otros fuera.
Local Repository	Sellar la caja y ponerle etiqueta.	(`git commit`). Cierras la caja definitivamente, le pones fecha, autor y un mensaje describiendo el contenido. Queda guardada.
Remoto (GitHub)	Enviar la caja al almacén.	(`git push`). La caja viaja a los servidores de GitHub para que otros puedan verla o descargarla.

Estados posibles de un archivo: untracked (sin seguimiento), modified (modificado en la mesa), staged (dentro de la caja) o committed (caja sellada).

4. Configuración inicial

Antes de hacer tu primer guardado, Git necesita saber quién eres para firmar tus aportaciones. Esto se hace una sola vez en tu ordenador:

$ git config --global user.name "Tu Nombre"
$ git config --global user.email "tu@email.com"

# Nombrar la rama principal 'main' por defecto (recomendado)
$ git config --global init.defaultBranch main

# Configurar el editor por defecto (evita bloqueos con Vim)
$ git config --global core.editor "code --wait"

# Verificar toda la configuración
$ git config --list

Escape de emergencia (La trampa de Vim): Si alguna vez tu terminal cambia de aspecto repentinamente, aparecen símbolos ~ a la izquierda y no puedes escribir con normalidad, has entrado accidentalmente en Vim (un editor clásico muy hostil para principiantes). Para salir de ahí y volver a la normalidad, escribe exactamente :q! y presiona Enter.

5. Del IDE a Git: crear un repositorio local

5.1 Inicializar un repositorio

Abre la terminal de tu editor (IDE), asegúrate de estar dentro de la carpeta correcta y ejecuta:

# Inicializa Git (crea una base de datos oculta)
$ git init

# Comprueba el estado. Los archivos nuevos aparecerán en rojo (Untracked)
$ git status

Se crea una carpeta oculta llamada .git. Esta carpeta es tu repositorio. Contiene todo tu historial. Nunca la modifiques ni la borres manualmente. Si quieres verificar que se ha creado correctamente, escribe ls -a en tu terminal para ver los archivos ocultos.

5.2 El archivo .gitignore

No todo el contenido de tu proyecto debe guardarse (ej. contraseñas, archivos autogenerados). Crea un archivo llamado literalmente .gitignore en la raíz de tu proyecto para excluir elementos.

# Ejemplo de .gitignore
node_modules/      # Dependencias pesadas
__pycache__/       # Archivos generados automáticamente
.env               # Contraseñas y claves API

Si te equivocas: Si haces git add de un archivo sensible por error y *luego* lo añades al .gitignore, Git lo seguirá rastreando. Usa:

$ git rm --cached nombre_del_archivo

6. Comandos del día a día

El flujo básico que repetirás constantemente al programar es el siguiente:

git status (Revisar qué has cambiado)
git add (Preparar los archivos)
git commit (Guardar en el historial)

6.1 git status - ¿qué ha cambiado?

Es tu comando de diagnóstico. Úsalo siempre antes de realizar una acción. Te indicará qué archivos están modificados (rojo) y cuáles están listos para guardarse (verde).

6.2 git add - preparar cambios

Comando	Qué hace
`git add archivo.py`	Añade solo el archivo especificado.
`git add .`	Añade TODOS los cambios de la carpeta actual.
`git add -p`	(Avanzado) Te pregunta bloque por bloque si quieres incluir un cambio.

6.3 git commit - guardar en el historial

El mensaje del commit debe ser claro y descriptivo. Sirve para que tus compañeros y tu "yo" del futuro entiendan qué cambios se aplicaron.

$ git commit -m "Añade botón de login en el menú principal"

# Ver el historial de cambios
$ git log --oneline
a3f8c12 Añade botón de login en el menú principal
2c9a831 Primer commit: estructura inicial

6.4 git stash - guardar temporalmente

Si estás trabajando en un archivo pero surge una urgencia, puedes pausar tu trabajo sin hacer commit para mantener el historial limpio:

Comando	Qué hace
`git stash`	Guarda tus modificaciones a medias en un área temporal y deja los archivos limpios.
`git stash pop`	Recupera las modificaciones guardadas a tu editor y las elimina del stash.
`git stash list`	Muestra una lista de todos los trabajos que tienes guardados en estado de pausa.
`git stash drop`	Elimina el último trabajo pausado sin aplicarlo (útil para limpiar memoria residual).

7. Ramas (branches): trabajar en paralelo

Una rama te permite tener una línea de desarrollo paralela. Por defecto, siempre trabajas en la rama principal llamada main (que contiene el código estable y funcional). Si deseas experimentar con nuevas características, puedes abrir una rama paralela (por ejemplo, feature/nueva-opcion). Allí podrás realizar múltiples *commits* sin afectar de ninguna manera a la versión principal.

💡 Comprendiendo el sistema de archivos al cambiar de rama

Un concepto técnico fundamental para comprender Git es saber que la herramienta modifica dinámicamente tu sistema de archivos en el disco duro local. Por ejemplo: si partiendo de la rama main creas una nueva rama feature, y añades un archivo nuevo dentro de ella... dicho archivo desaparecerá de tu explorador de archivos al ejecutar de vuelta un checkout hacia main.

A pesar de aparentar un error o una pérdida accidental, el archivo simplemente permanece documentado de manera exclusiva en el historial de la rama feature. En el momento de efectuar nuevamente un checkout hacia esa rama, Git se encargará de restaurar la información en su ubicación de origen automáticamente.

Leyenda del diagrama (Cada "C" es un Commit o punto de guardado):

C1 y C2: Tu proyecto base avanza de forma estable en la rama main.
C3 y C4: Al hacer checkout, abres la rama paralela feature. Aquí trabajas en la nueva funcionalidad. Estos commits (C3 y C4) son invisibles para la rama main, logrando un entorno seguro y aislado.
C5: Ejecutas git merge. Las líneas convergen para unificar el historial, fusionando por fin todo el trabajo finalizado de feature de vuelta a main.
C6: El proyecto, ahora actualizado con la nueva funcionalidad, continúa su ciclo natural en la rama main.

Comando	Qué hace
`git branch`	Muestra tus ramas locales (la activa tiene un `*`).
`git branch -a`	Muestra absolutamente todas las ramas, tanto las de tu PC como las subidas a GitHub.
`git checkout -b mi-rama` `git switch -c mi-rama`	Crea una rama nueva y te mueve a ella de inmediato (`switch` es la alternativa más moderna).
`git checkout main`	Te devuelve a la rama principal.
`git merge mi-rama`	Estando en `main`, fusiona los cambios de `mi-rama` hacia `main`.
`git branch -d mi-rama`	Elimina una rama localmente. Se utiliza para limpiar el repositorio tras haber realizado el `merge`.

8. De Git a GitHub: el repositorio remoto

8.1 Conectar tu proyecto local con GitHub

$ git remote add origin https://github.com/tu-usuario/mi-proyecto.git

El término origin es una convención estándar. Simplemente funciona como un atajo (un alias) para evitar tener que escribir la URL completa del repositorio cada vez que vayas a subir código.

🔗 HTTPS vs SSH (¿cuál elegir?)

A la hora de copiar la URL de tu repositorio en GitHub verás dos opciones:

HTTPS (recomendado para empezar): Empieza por https://. Es la opción más sencilla. La primera vez que hagas git push, GitHub te pedirá tu nombre de usuario y un token de acceso personal (no tu contraseña normal). Puedes generarlo en GitHub → Settings → Developer Settings → Personal Access Tokens.
SSH (más avanzado): Empieza por git@github.com:. Una vez configurado, nunca más te pedirá contraseña. Es el método preferido por profesionales, pero requiere generar un par de claves en tu ordenador. Cuando domines lo básico, es el siguiente paso natural.

Conclusión para principiantes: usa HTTPS ahora y pasa a SSH cuando te sientas cómodo.

8.2 Subir y bajar cambios

git push origin main: Envía tus commits locales hacia GitHub.
git pull: Descarga los cambios recientes de GitHub y los integra localmente.
git fetch: Descarga la información de GitHub sin modificar tus archivos locales.

El error más común: "Push rejected" (Non-fast-forward). Si intentas hacer git push y la terminal te devuelve un error indicando que tu actualización fue rechazada ("Updates were rejected because the remote contains work that you do not have locally"), significa que la nube tiene código más reciente que tú. La regla de oro: Ejecuta siempre git pull primero, resuelve los conflictos si los hay, y luego vuelve a intentar hacer git push.

8.3 Colaboración Open Source (El ciclo del Fork)

Para colaborar en proyectos donde no tienes permisos de escritura, el flujo de trabajo forma un triángulo entre tres puntos: el proyecto original, tu cuenta de GitHub y tu ordenador local.

Leyenda del flujo de colaboración:

1. Fork: Creas en tu propia cuenta de GitHub una copia gemela e independiente del proyecto original ajeno.
2. Clone: Te descargas tu copia a tu disco duro local para poder editar el código con tu IDE.
3. Push: Subes tu código modificado desde tu PC hacia *tu copia* en GitHub. Aún no has tocado el proyecto original.
4. Pull Request: Notificas al autor original desde GitHub proponiendo que integre los cambios de tu copia a su proyecto oficial.

9. Flujo de trabajo completo

Actualizar: git pull
Crear espacio: git checkout -b feature/nueva-tarea
Programar: Edita tus archivos.
Revisar: git status
Preparar: git add .
Guardar: git commit -m "Descripción"
Subir: git push origin feature/nueva-tarea
Pull Request: GitHub detectará tu nueva rama y te mostrará un botón amarillo "Compare & pull request" en la página de tu repositorio. Haz clic, escribe un título y descripción explicando qué hiciste y por qué, y finalmente haz clic en "Create pull request". Un compañero (o tú mismo) revisará los cambios antes de fusionarlos con main.

10. Conflictos de merge: cuando dos ramas chocan

Los conflictos ocurren cuando dos personas editan exactamente la misma línea de un archivo. Al intentar unificar los cambios, Git detecta la colisión, pausa el proceso y te pedirá que decidas cuál es la versión definitiva.

<<<<<<< HEAD (Tu código actual)
color = "rojo"
=======
color = "azul" (El código entrante)
>>>>>>> feature/otra-rama

⚠️ No entres en pánico: el conflicto es un proceso rutinario

Observar texto inyectado con símbolos como <<<<<<< suele resultar alarmante, pero es un mecanismo perfectamente normal. Hoy en día, la inmensa mayoría de editores profesionales (como VS Code) identifican este patrón y superponen opciones de resolución con un solo clic: "Aceptar el cambio actual", "Aceptar el cambio entrante" o "Aceptar ambos".

Selecciona tu opción preferida (o elimina de forma manual todo rastro de los marcadores de Git si optas por editar en texto plano). Cuando el código quede unificado y funcional, guárdalo y finaliza el proceso ejecutando de nuevo un git add . seguido de un último git commit.

11. Deshacer cosas y Diagnóstico: cuando algo sale mal

HEAD es un puntero interno de Git que indica en qué commit exacto te encuentras en este momento. Es clave para los comandos de reversión.

Operaciones para deshacer

Situación	Comando para solucionarlo
Me equivoqué y quiero volver al último punto de guardado (sin add).	`git restore archivo.py`
Hice `git add` por accidente y quiero sacarlo de la zona de preparación.	`git restore --staged archivo.py`
Olvidé añadir un archivo al último guardado que acabo de hacer.	`git add archivo.py` seguido de `git commit --amend --no-edit`
Escribí mal el mensaje del último `commit`.	`git commit --amend -m 'nuevo mensaje'`
Borré un archivo hace tiempo y necesito recuperarlo del historial.	`git checkout <hash_del_commit> -- archivo.py`
Necesito deshacer los cambios de un commit antiguo de forma segura.	`git revert HEAD` (o el hash específico)
Quiero deshacer el último commit pero conservar los cambios en mis archivos para poder corregirlos.	`git reset --soft HEAD~1`

Herramientas de diagnóstico profesional

Comando	Qué analiza
`git log --oneline --graph`	Muestra el historial dibujando un árbol visual de cómo se han fusionado las ramas.
`git diff --staged`	Muestra las diferencias exactas de código de los archivos que ya están en la "caja" (staging).
`git show <hash>`	Muestra el detalle técnico completo (autor, fecha, código añadido/borrado) de un commit concreto.
`git blame archivo.py`	Muestra línea por línea quién fue el último usuario que modificó el código y en qué commit lo hizo.

12. Buenas prácticas y Seguridad

Commits pequeños e independientes: Un commit debe representar un único cambio lógico.
Revisa antes de confirmar: Utiliza git diff antes de hacer tus commits.
Mantén la estabilidad: La rama main siempre debe contener código funcional.
Usa el inglés: Es el estándar en la industria tecnológica para nombrar ramas y commits.

Seguridad: Lo que nunca debe llegar a GitHub

Si subes datos sensibles, quedan en el historial público permanentemente. Aplica estas soluciones:

Elemento a proteger	Solución profesional recomendada
Contraseñas y claves API	Usa archivos `.env` y asegúrate de incluirlos en el `.gitignore`. Crea un archivo `.env.example` con valores vacíos para el equipo.
Credenciales de Bases de Datos	En entornos serios, utiliza gestores de secretos centralizados como HashiCorp Vault o AWS Secrets Manager.
Tokens de acceso y despliegue	Si automatizas procesos, inyéctalos usando GitHub Secrets para pipelines CI/CD.
Archivos de build o compilados	Carpetas como `dist/`, `build/` o archivos `.pyc` deben estar estrictamente excluidos vía `.gitignore` para no inflar el repositorio.

13. Chuleta rápida de comandos

Nota sobre sintaxis: Cuando veas símbolos como <rama> o <URL>, significa que debes sustituir todo ese bloque por el texto real. NO escribas los símbolos de mayor/menor qué en tu consola (ej. git clone https... y NO git clone <https...>).

Comando Principal	Formato de uso exacto	Explicación breve
Inicializar	`git init`	Crea un repositorio nuevo en la carpeta actual.
Clonar	`git clone <URL>`	Descarga un proyecto de GitHub a tu ordenador.
Estado	`git status`	Muestra qué archivos están modificados. (Usar siempre)
Añadir (Staging)	`git add .`	Prepara todos los archivos modificados para el guardado.
Guardar (Commit)	`git commit -m "Mensaje"`	Guarda los cambios en el historial permanentemente.
Subir (Push)	`git push origin <rama>`	Envía tus commits locales al servidor de GitHub.
Bajar (Pull)	`git pull`	Descarga y fusiona los cambios de GitHub.
Crear Rama	`git checkout -b <rama>`	Crea una nueva rama y te mueve a ella.
Cambiar Rama	`git checkout <rama>`	Te mueve a una rama que ya existe.
Fusionar	`git merge <rama>`	Integra los cambios de la rama indicada en la tuya.
Deshacer (Archivo)	`git restore <archivo>`	Revierte un archivo a su estado original.
Deshacer (Commit)	`git revert HEAD`	Deshace de forma segura el último commit.

Ejercicio práctico final (El ciclo completo):

Para consolidar los conocimientos, ejecuta este flujo destructivo para perder el miedo a Git:

Preparación local: Abre tu terminal, crea una carpeta (mkdir bootcamp_git), entra en ella (cd bootcamp_git) e inicializa Git (git init).
Primer commit: Crea un archivo historia.txt y escribe una línea. Prepara el archivo (git add .) y guárdalo (git commit -m "Inicio").
Preparación remota: Ve a GitHub.com, haz clic en el botón verde "New" (Nuevo repositorio). Nómbralo bootcamp_git. No marques ninguna casilla adicional (ni README ni gitignore). Haz clic en "Create repository".
Conexión y subida: Copia la URL HTTPS de tu nuevo repositorio. En tu terminal vincula el repositorio (git remote add origin <TU_URL_COPIADA>) y sube el código (git push -u origin main).
Destrucción local (Prueba de confianza): Sal de la carpeta en tu terminal (cd ..) y borra la carpeta bootcamp_git de tu ordenador manualmente a través de tu explorador de archivos. Tu código local ha desaparecido.
Resurrección (Clone): Recupera tu código desde la nube. Ejecuta git clone <TU_URL_COPIADA>. Entra en la carpeta restaurada (cd bootcamp_git) y verifica que tu historial sigue intacto ejecutando git log --oneline.
Limpieza: Ve a tu repositorio en GitHub, accede a Settings (Configuración), baja hasta la "Danger Zone" y elimina el repositorio remoto para mantener tu perfil ordenado.

14. Errores Comunes de Configuración

Al conectar GitLab o GitHub con tu ordenador local por primera vez (el primer git push), pueden aparecer barreras de seguridad. Estos son los dos bloqueos que le ocurren al 90% de los estudiantes y cómo resolverlos al instante:

Error en la terminal	¿Por qué pasa?	Solución rápida
error: GH007: Your push would publish a private email address	Tienes activada una protección de privacidad en GitHub ("Keep my email addresses private"), pero Git en tu terminal intentó adjuntar tu correo real a los commits. GitHub lo bloquea.	Ve a github.com/settings/emails y desmarca la casilla "Keep my email addresses private". (Si deseas mantenerlo privado, copia tu correo anónimo de GitHub y configúralo en tu terminal con `git config user.email "TU_CORREO_ANONIMO"`).
git@github.com: Permission denied (publickey).	Intentaste conectar usando el enlace seguro tipo SSH (`git@github...`), pero no tienes llaves encriptadas generadas en tu ordenador, o no se las has dado a GitHub.	La solución más sencilla para principiantes es usar el túnel HTTPS normal en lugar de SSH. Ejecuta: `git remote set-url origin https://github.com/TU_USUARIO/TU_REPO.git` Y vuelve a intentar el `git push`.
dquote>	Este no es un error de nube, sino un despiste al teclear. Se te ha olvidado poner las comillas de cierre (") en el último mensaje de `git commit`.	Escribe unas comillas dobles (`"`) en la terminal y presiona Enter para destrabarlo, o pulsa `Ctrl + C` para cancelar el comando.