GitHub para quien no escribe el código

Si nunca has usado GitHub, ignora cómo suele describirse. No es una red social para programadores, no estás ahí para leer el código de nadie, y los cuadraditos verdes no son un marcador que tengas que rellenar.

Es un sistema de guardado con historial, alojado en un sitio que no es tu portátil. Eso es todo.

Para un vibe coder se gana el sitio por una razón concreta. En algún momento — no quizá, en algún momento — una sesión reescribirá algo que ya funcionaba. Refactorizará un fichero que te gustaba, borrará una función que decidió que no se usaba, o arreglará un bug introduciendo dos en silencio. Sin commits, ese trabajo se ha ido y tu única recuperación es describirlo otra vez de memoria a un modelo que ha olvidado la conversación. Con commits, la recuperación es una frase.

Esta guía es todo lo que necesitas para eso, y nada que no necesites.

Git y GitHub no son lo mismo

Merece diez segundos, porque confundirlos es lo que hace confuso todo lo demás.

Git es un programa en tu ordenador. Registra versiones de una carpeta. Funciona sin internet, sin cuenta y sin web, y es lo que hace todo el trabajo real.

GitHub es una web que guarda una copia de un repositorio Git y añade lo que una web puede añadir: una página para navegarlo, un sitio para otras personas, automatización que corre cuando subes algo.

Así que cuando tu agente “commitea”, eso es Git, en local, al instante. Cuando hace “push”, eso es la copia viajando a GitHub. Por eso puedes trabajar en un avión y por eso un commit no es una copia de seguridad hasta que se ha subido.

Las alternativas — GitLab, Bitbucket, Codeberg — son el mismo Git por debajo con otra web encima. Nada de esta guía cambia si eliges una de ésas.

Las siete palabras que cubren casi todo

Van en inglés porque así es como las verás en GitHub y en la terminal:

Dos más que verás y que puedes ignorar casi siempre: origin es el apodo por defecto de “la copia que está en GitHub”, y main es el nombre por defecto de la rama principal.

¿Necesito aprender comandos de Git?

No, y ésta es la parte que nadie le cuenta a quien empieza. Necesitas tres frases que decirle a tu agente, y él ejecuta los comandos.

• Commitea esto con un mensaje claro.
• ¿Qué ha cambiado desde el último commit?
• Deshaz todo desde el último commit.

Ésa es la interfaz entera de tu primer mes. Lo que sí necesitas es entender qué significan esas tres cosas, que es para lo que está el resto de esta página — porque el fallo habitual no es teclear el comando equivocado, es pedir el tipo de deshacer equivocado.

Si prefieres botones a frases, GitHub Desktop es gratuito, muestra los ficheros cambiados como un diff visual y convierte commit y push en dos clics. Mucha gente que publica productos reales no usa nunca la terminal para Git.

Dónde vive tu código mientras trabajas

Los mensajes de Git hablan de ficheros “staged”, “tracked” y “untracked”, y nada de eso tiene sentido hasta que sabes que hay tres sitios donde puede estar un cambio:

El área de staging es la parte que al principio parece inútil. Su propósito es elegir: han cambiado doce ficheros, cuatro pertenecen a este commit, así que pones esos cuatro en staging. Como vibe coder commitearás casi siempre todo de golpe — pero necesitas saber que el staging existe, porque si no “changes not staged for commit” es un mensaje de error sobre nada.

git status es el comando de “dónde estoy”, y es el que merece la pena que sepas leer tú. Te dice en qué rama estás, qué ha cambiado, qué está en staging y si vas por delante o por detrás de GitHub. Cuando algo confunde, esto es lo primero que hay que mirar, y es completamente seguro: no cambia nada.

El primer fichero que importa: .gitignore

Antes de tu primer push, antes que nada: .gitignore es una lista de ficheros que Git no debe registrar nunca.

Como mínimo contiene:

.env
.env.local
node_modules/
.DS_Store
dist/

.env es el que importa. Ahí es donde viven tus API keys, y esa única línea es lo que impide que se publiquen la primera vez que subes algo. Los repositorios públicos los escanea continuamente gente que busca exactamente esto, y una clave filtrada se encuentra en minutos, no en días.

Pídelo explícitamente al montar el proyecto — añade un .gitignore apropiado para este stack, y asegúrate de que .env está dentro — y luego comprueba con tus propios ojos que .env aparece. Es una comprobación de treinta segundos que evita el error caro más habitual de quien empieza.

Haz el repositorio privado por defecto. Público es una decisión deliberada de publicar, y es mucho más fácil hacer público después un repositorio privado que despublicar algo, incluido todo lo que hay en su historial.

¿Cómo leo un diff sin leer código?

Un diff es lo que cambió, mostrado línea a línea. Las líneas verdes con + se añadieron, las rojas con - se quitaron, las grises son contexto sin cambios. No necesitas entender el código para sacarle valor real:

• ¿Cómo de grande es? Doce líneas cambiadas para una petición pequeña es normal. Cuatrocientas es una señal para parar y preguntar qué más ha hecho.
• ¿Qué ficheros? Si pediste un cambio de color y en la lista hay un fichero con auth, migration o schema en el nombre, ése es el momento de preguntar por qué.
• ¿Se ha borrado algo que no pediste borrar? Los bloques largos de rojo merecen una pregunta.

Ésa es toda la habilidad, y es la mayor parte de lo que una revisión de código te da en un proyecto en solitario. Enséñame el diff y explícame en lenguaje llano qué hace el cambio de cada fichero es una buena costumbre antes de cada commit.

¿Qué hace que merezca la pena escribir un mensaje de commit?

Su único trabajo es ayudar al tú del futuro a encontrar un momento en el tiempo. “Update” y “fixes” fracasan en eso; seis seguidos son indistinguibles.

Escribe cuál es el estado, no lo que hiciste: pantalla de login funciona, validación aún sin hacer. Seis semanas después, ese mensaje es lo que te deja decir “vuelve a cuando el login funcionaba” y que signifique algo preciso.

Commitea cuando algo funciona, no al final del día. El final del día es un punto de guardado para ocho horas de decisiones. Cada estado que funciona es un sitio al que puedes volver.

¿Cuándo necesito de verdad una rama?

Como vibe coder en solitario, menos a menudo de lo que dan a entender los tutoriales. Necesitas una cuando estás a punto de probar algo de lo que podrías arrepentirte: una refactorización grande, un cambio arriesgado de dependencia, un experimento del que sólo estás medio convencido.

La razón es que deshacer sale gratis. Estás en experiment, sale mal, te vuelves a main y borras la rama. Nada que desenredar, nada que revertir, ninguna discusión con el agente sobre qué cambió.

En el momento en que alguien más toca el repositorio, esto deja de ser opcional y pasa a ser una rama por cada pieza de trabajo — que es donde el vibe coding se pone genuinamente más difícil, y un problema distinto de éste.

¿Cómo deshago algo?

La sección más importante de esta página. Hay cuatro tipos de deshacer y pedir el que no es, es como la gente pierde trabajo intentando salvarlo.

1. Tienes cambios sin commitear y los quieres fuera.

git restore .

Todo lo posterior al último commit desaparece. Éste es el de cada día: la sesión salió mal, no había nada que valiera la pena, se empieza otra vez desde el último estado bueno.

2. Commiteaste, pero no has subido, y quieres el commit fuera.

git reset --soft HEAD~1   # deshace el commit, conserva los cambios
git reset --hard HEAD~1   # deshace el commit y los cambios

--soft es para “commit correcto, mensaje equivocado, momento equivocado”. --hard es para “esa dirección entera estaba mal”.

3. Ya subiste, y otras personas (o un despliegue) lo tienen.

git revert <commit>

Esto hace un commit nuevo que deshace el viejo. Es el seguro, porque añade al historial en lugar de reescribirlo, y nada de lo que ya tiene otra persona entra en conflicto con lo que tienes tú.

4. Crees que has perdido algo para siempre.

git reflog

Git guarda un registro privado de cada posición en la que ha estado tu rama durante unos noventa días, incluidos commits que “borraste” y ramas que quitaste. Casi nada se pierde de verdad. Éste es al que recurrir después de un --hard del que te arrepientes o de un force-push que se comió tu tarde — y merece la pena saber que existe precisamente porque el momento en que lo necesitas es el momento en que estás en pánico.

¿Qué es un conflicto de merge, y quién lo arregla?

Dos ramas cambiaron las mismas líneas. Git no va a adivinar qué versión gana, así que marca la sección en disputa en el fichero con <<<<<<< y >>>>>>> y se para.

No hay nada roto ni nada perdido. Las dos versiones están ahí mismo; alguien tiene que elegir.

Los agentes son buenos en esto, con una condición: cuéntales para qué era cada cambio. La decisión va de intención, no de sintaxis — este lado es la lógica nueva de precios, ése es el arreglo del bug de ayer, conserva los dos comportamientos obtiene una resolución correcta. “Arregla el conflicto” obtiene un cara o cruz.

¿Qué pasa si commiteo una API key?

Rótala. Ya. Ve al servicio, revoca la clave, emite una nueva.

Borrar el fichero en un commit posterior no hace nada, porque la clave sigue ahí en el historial, donde cualquiera puede leerla. En un repositorio público, da por hecho que se rastreó en minutos: esto está automatizado a escala.

GitHub ayuda en dos puntos, y merece la pena activar los dos. Secret scanning detecta formatos de clave conocidos en tu repositorio y te avisa. Push protection va más allá y bloquea el push antes de que el secreto llegue a aterrizar. Ninguno cubre todos los formatos, así que .gitignore sigue siendo la defensa de verdad.

Limpiar la clave del historial después es posible y engorroso. También es secundario: una vez rotada la clave, la que está en el historial es una cadena muerta.

¿Qué más es GitHub, más allá del almacenamiento?

Cosas con las que te vas a encontrar, en una línea cada una:

• Issues — una lista de pendientes pegada al proyecto. Vale para notas en solitario, aunque un board de verdad es mejor en cuanto el trabajo toma forma.
• Actions — automatización que corre al hacer push. Así es como corren los tests y como se disparan los despliegues. Te lo encontrarás la primera vez que conectes un host.
• Releases y tags — un nombre clavado a un commit concreto. v1-launch es un marcador que dice esta versión era buena, y no cuesta nada.
• Pages — alojamiento estático gratuito directamente desde un repositorio. Vale para una landing, no para nada con backend.
• Fork — tu propia copia del repositorio de otra persona. Relevante cuando quieres cambiar el proyecto de código abierto de alguien.
• Dependabot — abre pull requests cuando una dependencia tiene un arreglo de seguridad. Gratis, merece la pena dejarlo activado.
• Codespaces — un entorno de desarrollo completo en el navegador. Útil cuando quieres trabajar desde una máquina que no tiene nada instalado.

Cosas que te confundirán exactamente una vez

Cada una de éstas produce un momento de alarma genuina, y cada una es inofensiva una vez la has visto.

“You are in ‘detached HEAD’ state.” Miraste un commit antiguo y ahora estás parado encima de él en lugar de sobre una rama. Los commits hechos aquí no pertenecen a nada y son fáciles de perder. git switch main te devuelve. No hay nada roto.

Tu repositorio contiene otro repositorio. Un agente ejecutó git init dentro de una carpeta que ya estaba en un repo, normalmente mientras montaba algo. GitHub muestra entonces una carpeta que no puedes abrir y que no contiene nada. El arreglo es borrar la carpeta .git interior — y la pista es un commit que añade un directorio pero ninguno de los ficheros que hay dentro.

Un fichero es demasiado grande para subirlo. GitHub rechaza ficheros individuales de más de 100 MB, y un vídeo, un volcado de base de datos o un node_modules que se escapó del .gitignore van a chocar con eso. La trampa es que quitar el fichero no arregla el push, porque sigue en el historial: hay que deshacer el commit que lo añadió. Mucho más fácil prevenirlo: revisa el .gitignore antes del primer push.

Tus dos máquinas no se ponen de acuerdo. Commiteaste en el portátil, subiste, y luego commiteaste en el sobremesa sin hacer pull. Git rechazará el segundo push. git pull primero, resuelve lo que te pregunte, y luego push. La costumbre que lo evita del todo es hacer pull al empezar una sesión y no al terminarla.

El agente ha commiteado como otra persona. Los commits llevan el nombre y el email de tu configuración local de Git, que en una máquina recién estrenada puede estar vacía o mal. Merece la pena configurarlo una vez, o tu historial estará firmado por “unknown”.

Trucos que se pagan solos

• Commitea antes de cada sesión con el agente, no después. El commit no es un registro de lo que hiciste, es el punto de guardado que estás a punto de arriesgar. Diez segundos, y convierte cada desastre en un git restore .
• Pide el diff antes de aceptar. Enséñame qué has cambiado y por qué pilla el extra servicial que no querías, que es el fallo más habitual que sobrevive hasta producción.
• Una rama por experimento, y borrarla es el deshacer. Más barato que cualquier revert.
• git stash cuando el agente se queje de un árbol sucio. Se guarda en el bolsillo tu trabajo sin commitear; git stash pop te lo devuelve. Mejor que commitear basura para desatascarte.
• --force-with-lease, nunca --force a secas. Los dos reescriben lo que hay en GitHub. El primero se niega si alguien ha subido algo mientras tanto; el segundo lo sobrescribe sin preguntar.
• Protege main en cuanto haya algo real dentro. La protección de ramas de GitHub puede exigir un pull request antes de fusionar, lo que hace que “el agente subió directo a main a las 2 de la mañana” sea estructuralmente imposible en lugar de meramente desaconsejado.
• Etiqueta la versión que funcionaba. Antes de un cambio grande, v-works no cuesta nada y se encuentra sin esfuerzo, a diferencia de un hash de commit que no vas a reconocer jamás.
• Haz squash al fusionar. Catorce commits de “wip”, “fix”, “esta vez sí” se colapsan en una entrada con sentido, y tu historial sigue siendo legible por un humano — y por el siguiente agente que lo lea.
• Acuérdate de que reflog existe antes de necesitarlo. En el momento en que lo necesites no estarás en condiciones de descubrirlo.

Qué hacer el primer día

1. Crea la cuenta. Haz el primer repositorio privado.
2. Pon el .gitignore en su sitio con .env dentro, y compruébalo con tus propios ojos.
3. Pídele al agente que haga el primer commit y lo suba. Mira el repositorio en GitHub y ve tus ficheros ahí.
4. Y después, cada vez que algo funcione: commitea esto con un mensaje claro.

Ésa es la práctica entera. Todo lo demás de esta página está ahí para el día en que algo salga mal — y la razón para leerlo ahora es que el día en que algo sale mal es un mal día para estar aprendiendo qué tipo de deshacer necesitas.

El resto del montaje en el que esto encaja — el modelo, el host, el stack, las salvaguardas — son seis decisiones, y el control de versiones es la que todas las demás dan por hecha que ya tienes.