En el Módulo 1 vimos el pipeline completo, y la primera etapa — la puerta de entrada de todo cambio — es Git. Antes de hablar de convenciones de equipo o de CI, necesitas dominar la herramienta que registra cada línea que escribes. Este módulo es el manual de campo: los comandos que vas a teclear todos los días, sin adornos. Complementa a Preparación para el workshop de GitHub; aquí nos enfocamos en el uso diario desde la terminal.

La tesis del módulo

Git es la máquina del tiempo de tu código: registra cada cambio, permite volver atrás y deja trabajar a varias personas sin pisarse. Diez comandos cubren casi todo el día. Dominarlos es la base de todo el pipeline.

El modelo mental: tres zonas y un remoto

Git mueve tus archivos por tres zonas locales antes de subirlos al remoto (el repositorio compartido, típicamente en GitHub). Entender este flujo es entender Git:

 ┌──────────────────────┐
 │ WORKING DIR          │  tus archivos, como los editas
 └──────────┬───────────┘
            │  git add
            ▼
 ┌──────────────────────┐
 │ STAGING              │  lo que irá al próximo commit
 └──────────┬───────────┘
            │  git commit
            ▼
 ┌──────────────────────┐
 │ REPO LOCAL           │  historia de commits, en tu máquina
 └──────────┬───────────┘
            │  git push
            ▼
 ┌──────────────────────┐
 │ REMOTO (GitHub)      │  compartido con el equipo
 └──────────┬───────────┘
            │  git pull
            ▼
   vuelve a tu working dir

Working directory: los archivos como los ves y editas.
Staging (o index): la sala de espera. Con git add eliges qué cambios entran al próximo commit.
Repo local: con git commit sellas esos cambios en la historia, en tu máquina.
Remoto: con git push subes tu historia local a GitHub; con git pull bajas lo que otros subieron.

Empezar: init y clone

git init                              # crea un repo Git en la carpeta actual
git clone https://github.com/org/agente.git   # copia un repo que ya existe

git init convierte una carpeta cualquiera en repositorio. git clone baja uno que ya vive en GitHub — lo más común cuando te sumas a un proyecto.

El ciclo diario: status, add, commit, push

git status                            # qué cambió, qué está en staging
git add src/agent.py                  # sube un archivo al staging
git add .                             # sube TODO lo cambiado (cuidado con esto)
git commit -m "feat: agregar tool de búsqueda"   # sella el commit con mensaje
git push                              # sube tus commits al remoto

git status es el comando que más vas a usar: te dice en qué zona está cada archivo. Córrelo antes y después de todo. El mensaje de -m describe el cambio — en el Módulo 3 veremos cómo escribirlo con el estándar de la empresa.

Traer cambios: pull

git pull                              # baja y fusiona lo del remoto

git pull es en realidad dos pasos: baja los commits nuevos del remoto (fetch) y los fusiona con los tuyos (merge). Hazlo antes de empezar a trabajar cada día, para partir desde la última versión del equipo.

Ramas: branch, switch, merge

Una rama (branch) es una línea de trabajo paralela: cambias sin tocar el código principal hasta estar listo. Es la base del trabajo en equipo.

git branch                            # lista tus ramas; marca la actual con *
git switch -c feature/busqueda-web    # crea una rama nueva y se cambia a ella
git switch main                       # vuelve a la rama principal
git merge feature/busqueda-web        # fusiona esa rama en la actual

git switch es la forma moderna de moverse entre ramas; git checkout <rama> hace lo mismo y lo verás en proyectos antiguos. Con -c (de create) creas y saltas en un solo paso.

Ver la historia: log y diff

git log --oneline                     # historia compacta, un commit por línea
git log --oneline --graph             # además dibuja las ramas y merges
git diff                              # cambios aún NO agregados al staging
git diff --staged                     # cambios YA en staging, listos para commit

git diff te muestra exactamente qué cambiaste, línea por línea, antes de commitear. Revísalo siempre: es tu última oportunidad de cazar un print() de debug o una API key que se te coló.

Resolver un conflicto de merge paso a paso

Un conflicto ocurre cuando dos ramas cambiaron la misma línea del mismo archivo, y Git no sabe cuál dejar. No es un error: es Git pidiéndote una decisión.

Supón que fusionas y aparece esto:

git merge feature/nuevo-prompt
# Auto-merging src/agent.py
# CONFLICT (content): Merge conflict in src/agent.py
# Automatic merge failed; fix conflicts and then commit the result.

Abre src/agent.py y verás las marcas de conflicto:

def system_prompt():
<<<<<<< HEAD
    return "Eres un asistente de soporte."
=======
    return "Eres un asistente de soporte técnico especializado."
>>>>>>> feature/nuevo-prompt

Entre <<<<<<< HEAD y ======= está tu versión (la rama actual).
Entre ======= y >>>>>>> está la versión que entra (la otra rama).

Editas a mano dejando la versión final que quieres, y borras las tres líneas de marcas:

def system_prompt():
    return "Eres un asistente de soporte técnico especializado."

Luego cierras el merge:

git add src/agent.py                  # marca el conflicto como resuelto
git commit                            # confirma el merge (mensaje ya sugerido)

Ojo: el conflicto no se “arregla” con git add a ciegas. Tienes que abrir el archivo, decidir el contenido final y borrar las marcas <<<<<<<, =======, >>>>>>>. Si las dejas, commiteas basura que no compila.

El .gitignore: qué NUNCA sube

El archivo .gitignore lista lo que Git debe ignorar: no lo versiona ni lo sube. Un .gitignore mínimo para un agente en Python:

# Secretos: NUNCA al repo
.env

# Python
__pycache__/
*.pyc
.venv/
venv/

# Datos y modelos pesados
*.sqlite
models/

# Editor
.vscode/
.idea/

La línea más importante es .env. Ese archivo guarda tus API keys y credenciales, y jamás debe subir al repositorio. En el Módulo 4 veremos en detalle cómo manejar secretos; por ahora, la regla es sagrada: .env va en .gitignore desde el primer commit.

Deshacer con seguridad

Aquí es donde la gente rompe cosas. Tres comandos, tres propósitos distintos:

Comando	Qué hace	¿Seguro en historia compartida?
`git revert <commit>`	Crea un commit nuevo que deshace otro	Sí — no reescribe historia
`git reset <commit>`	Mueve la rama atrás, “borra” commits locales	No — reescribe historia
`git restore <archivo>`	Descarta cambios de un archivo en el working dir	Sí, pero pierdes lo no guardado
`git stash`	Guarda cambios a un lado, temporalmente	Sí — no toca la historia

git revert a1b2c3d                    # deshace ese commit con uno nuevo
git reset --soft HEAD~1               # deshace el último commit, conserva cambios
git restore src/agent.py              # descarta cambios NO commiteados del archivo
git stash                             # guarda tus cambios y deja limpio el dir
git stash pop                         # recupera lo guardado

La regla de oro: si el commit ya está en el remoto (otros lo tienen), usa git revert. Crea un commit nuevo que anula el anterior sin reescribir la historia, así nadie se rompe. git reset solo es seguro en commits que aún no subiste, porque reescribe la línea de tiempo.

git stash es tu aliado cuando estás a medias y necesitas cambiar de rama rápido: guarda todo a un lado, la dejas limpia, y con git stash pop recuperas tu trabajo después.

Ojo: nunca hagas git reset --hard sobre commits que ya subiste al remoto. Reescribes la historia compartida y obligas a todo el equipo a resolver el desastre. En ramas compartidas, revert siempre.

Errores comunes

git add . sin mirar. Sube archivos basura, temporales o — peor — un .env que olvidaste ignorar. Revisa con git status antes.
Commitear un secreto. Si sube una API key, no basta con borrarla en el siguiente commit: queda en la historia. Hay que rotar la clave y limpiar el historial. Prevenir con .gitignore es infinitamente más barato.
git reset --hard en rama compartida. El error que reescribe la historia de todos. Usa revert.
No hacer git pull antes de empezar. Trabajas sobre una versión vieja y te ganas conflictos evitables.
Dejar las marcas de conflicto en el archivo. <<<<<<< no es un comentario: rompe el código. Bórralas todas al resolver.
Mensajes de commit vacíos o inútiles (git commit -m "cambios"). La historia legible es el punto; el Módulo 3 le pone estándar.

La frase para llevarse

“Git no es para subir código: es la máquina del tiempo que te deja equivocarte sin miedo, porque siempre puedes volver.”

Qué viene

Módulo 3: convenciones de equipo. Ya sabes usar Git; ahora aprenderás a usarlo como en la empresa — nombres de ramas, Conventional Commits, Pull Requests, code review y los flujos GitFlow vs trunk-based. Ahí Git deja de ser tuyo y pasa a ser del equipo.

Deploy de Agentes — Módulo 2: Git esencial — los comandos del día a día