En la lección 03-02 nos encontramos por primera vez con este mensaje:

Y dijimos que había una tercera salida, además de confirmar o descartar: apartar los cambios. Prometimos una lección entera. Es esta.

git stash es el cajón de sastre de Git: coge todo lo que tienes a medias en el directorio de trabajo y en el índice, lo guarda en un sitio seguro, y te deja la copia de trabajo limpia como si acabaras de clonar. Después, cuando quieras, lo recuperas.

El escenario es siempre el mismo y le pasa a todo el mundo: estás a mitad de algo, con código que no compila y que no merece un commit, y llega una urgencia. Carla lo va a vivir en esta lección. Y al final veremos lo que casi nadie mira: que el stash no tiene nada de mágico, que por dentro son commits normales en una referencia oculta, exactamente los mismos objetos del modelo de datos de la lección 01-04.

1. El escenario: Carla y la urgencia
2. git stash: qué guarda y qué no
3. Ficheros sin seguimiento e ignorados: -u y -a
4. La pila: list, show, apply, pop, drop, clear
5. apply frente a pop
6. Referirse a una entrada concreta
7. git stash push: mensajes, rutas y modo interactivo
8. --keep-index y --staged
9. git stash branch: cuando el stash ya no encaja
10. Cómo funciona por dentro
11. Riesgos: stashes olvidados y falsas copias de seguridad

Carla está en funcionalidad/orden-por-fecha, a media función. Ha tocado app.js y estilos.css, y ha creado un fichero nuevo, utilidades.js, que todavía no ha añadido al repositorio.

Llega un mensaje de Ana: el botón de borrar no funciona en producción y hay que corregirlo ya. Carla necesita cambiar a main, hacer la corrección y volver. Sus opciones:

Directorio limpio. Carla puede cambiar de rama sin que Git proteste, corregir el fallo, publicarlo y volver:

Todo vuelve a estar como estaba. Eso es git stash en su uso más básico. Ahora, los detalles que marcan la diferencia.

git stash sin argumentos es un alias de git stash push. Por defecto guarda:

• Los cambios en ficheros con seguimiento que están modificados en el directorio de trabajo.
• Los cambios en ficheros con seguimiento que están preparados en el índice.

Y no guarda:

• Los ficheros sin seguimiento (los que aparecen como ?? en git status).
• Los ficheros ignorados por .gitignore.

Esta es la primera trampa, y es grave. Si Carla hubiera hecho git stash sin -u:

app.js y estilos.css estarían apartados, pero utilidades.js seguiría ahí, sin seguimiento y sin apartar. Y como no lo aparta, tampoco lo devuelve: si Carla lo borrara por error pensando que está en el stash, lo perdería.

La lógica de Git tiene sentido —un fichero sin seguimiento nunca ha formado parte del repositorio, así que Git es conservador y no lo toca— pero la consecuencia práctica sorprende siempre la primera vez.

Recordando las tres zonas de la lección 01-03, el reparto es este:

Y un matiz que importa al recuperar: por defecto, el stash no conserva qué estaba preparado y qué no. Al hacer pop o apply, todo vuelve como "modificado sin preparar". Si necesitas conservar esa distinción, existe --index:

Con --index, lo que estaba en el índice vuelve al índice. Puede fallar si el estado actual no lo permite, en cuyo caso Git lo aplica todo sin preparar y te avisa.

Sobre -a: los ficheros ignorados suelen ser node_modules/, dist/, .env, ficheros de compilación... Apartarlos significa borrarlos del directorio de trabajo y meterlos en el stash. Con node_modules/ eso son decenas de miles de ficheros y una operación lentísima. Y con .env, tus credenciales locales pasan a estar dentro de objetos de Git, que es justo lo que no quieres. Usa -a de forma excepcional y consciente.

En cambio, -u es tan frecuentemente lo que quieres que mucha gente lo configura como comportamiento por defecto mediante un alias:

Los alias se ven a fondo en la lección 06-04, pero este vale la pena desde ya.

El stash no es un cajón único: es una pila. Puedes apartar varias veces, y cada nueva entrada se coloca encima.

• stash@{0} es siempre la más reciente.
• Los números se renumeran cada vez que añades o quitas una entrada. stash@{1} de hoy no es el mismo que el de mañana. Es un motivo excelente para poner mensajes descriptivos.
• El texto WIP on main: 7d3a8f4 ... es el mensaje automático cuando no le pones uno: la rama y el commit sobre el que se guardó.

Para ver el contenido de una entrada:

Un detalle: por defecto, git stash show no incluye los ficheros sin seguimiento que hubieras guardado con -u. Para verlos:

El repertorio completo de comandos:

git stash clear merece un aviso en negrita: borra toda la pila de golpe y no pregunta. Recuperar algo después es posible pero engorroso (hay que rebuscar objetos huérfanos con git fsck, técnica de la lección 09-04). Trátalo como rm -rf.

Las dos aplican los cambios guardados sobre tu directorio de trabajo. La diferencia está en qué pasa con la entrada después:

En qué se traduce esto en la práctica:

Usa pop en el caso normal: apartaste, hiciste otra cosa, vuelves. Es un solo comando y deja la pila limpia.

Usa apply cuando:

• Quieres aplicar los mismos cambios en dos ramas distintas.
• No estás seguro de que vayan a encajar y prefieres conservar la copia hasta comprobarlo.
• La rama actual ha cambiado mucho y sospechas que habrá conflicto.

El detalle que salva vidas: si pop provoca un conflicto, la entrada NO se elimina. Git aplica lo que puede, deja los marcadores de conflicto y conserva el stash por si acaso. Es un comportamiento deliberado y muy sensato. Pero tiene una consecuencia molesta: después de resolver el conflicto, la entrada sigue en la pila y tienes que borrarla tú:

Anota ese hash que imprime drop. Es la referencia al objeto del stash, y con él se puede recuperar una entrada borrada por error (lección 09-04). Es el mismo consejo que dimos al borrar ramas en 03-06, y por el mismo motivo.

Un aviso sobre los conflictos de stash: a diferencia de un merge o un rebase, aquí no hay --abort. Si pop conflictúa, estás en medio de la resolución y la única forma de volver atrás es descartar los cambios del directorio de trabajo (git checkout -- . o git reset --hard, con el cuidado que eso exige) sabiendo que el stash sigue a salvo en la pila.

Casi todos los comandos aceptan una entrada. Si la omites, se usa stash@{0}.

La notación stash@{N} es la misma sintaxis de reflog que viste en 02-06 aplicada a la referencia refs/stash. Y admite formas por tiempo:

En algunos intérpretes de comandos las llaves necesitan comillas o escape:

Desde Git 2.11 también se admite el número a secas, que es más cómodo:

Y recuerda: los números se renumeran. Si tienes tres entradas y borras la del medio, la que era stash@{2} pasa a ser stash@{1}. Nunca guardes un número apuntado en un papel; guarda el mensaje.

git stash push es la forma moderna y completa. git stash save "mensaje" es la forma antigua, todavía funciona, pero está desaconsejada y no admite rutas.

Mensaje descriptivo:

Es la mejora de calidad de vida más barata que existe con esta herramienta. Un git stash list con tres entradas llamadas WIP on main es inútil; con tres mensajes descriptivos, es un plan de trabajo.

Guardar solo unas rutas:

Los cambios de esos ficheros se apartan; el resto se queda en el directorio de trabajo. Es muy útil cuando has mezclado dos tareas en la misma sesión y quieres separar una para trabajar con la otra tranquilo.

Modo interactivo:

Trozo a trozo, igual que git add -p (lección 02-04), Git te pregunta por cada bloque de cambios si quieres apartarlo:

Las teclas son las mismas de siempre: y sí, n no, q salir, s dividir el trozo, e editarlo a mano.

Otras opciones de push:

Dos opciones parecidas de nombre y muy distintas de efecto. La tabla lo aclara todo; supongamos que tienes app.js preparado y estilos.css modificado sin preparar:

--keep-index guarda todo pero restaura en el directorio lo que estaba en el índice. Su uso clásico es probar un commit antes de hacerlo:

Es la forma correcta de asegurarse de que un commit es autocontenido y no depende de cambios que se han quedado fuera. Mucha gente descubre así que su commit "listo" no compilaba por sí solo.

Nota: con --keep-index, el stash contiene también lo preparado. Al hacer pop después del commit, esos cambios ya están confirmados y pueden conflictuar. En la práctica se suele combinar con --include-untracked y se acepta que el pop posterior a veces requiere un --skip mental: revisa con git stash show -p antes de recuperar.

--staged (desde Git 2.35) es más simple y más nueva: aparta solo lo que está en el índice y deja el resto. Es lo contrario del caso anterior, y sirve para "esto que ya tenía preparado me lo llevo a otra rama":

Problema clásico: guardaste un stash hace tres días, la rama ha avanzado mucho desde entonces y ahora git stash pop da un conflicto tras otro.

La causa es que el stash se guardó sobre un commit concreto y ahora se está aplicando sobre otro completamente distinto. La solución es aplicarlo donde encajaba:

Este comando hace cuatro cosas de una vez:

1. Crea una rama nueva en el commit sobre el que se guardó el stash.
2. Se cambia a ella.
3. Aplica el stash (que encaja perfectamente, porque el contexto es el original).
4. Elimina la entrada de la pila, ya que se ha aplicado con éxito.

Desde ahí puedes confirmar tranquilamente y después integrar la rama con merge o rebase, resolviendo los conflictos una sola vez y con contexto, en lugar de pelearte con un pop a ciegas.

Es la mejor salida cuando un stash "no entra". Y también la mejor forma de convertir un stash que se ha vuelto importante en trabajo de verdad.

Aquí es donde el stash deja de parecer magia. Retomamos el modelo de datos de la lección 01-04.

Cuando haces git stash, Git crea commits normales:

• Un commit con el estado del índice.
• Opcionalmente, un commit con los ficheros sin seguimiento (si usaste -u).
• Un commit de fusión cuyo primer padre es el HEAD actual, el segundo el commit del índice, y el tercero (si existe) el de los sin seguimiento. Este es el commit del stash.

Y guarda la referencia a ese commit en refs/stash. Comprobémoslo:

Un commit corriente. Veamos su interior con las mismas herramientas de 01-04:

Tres padres:

Y el tree del propio commit es el estado del directorio de trabajo. Con esos cuatro árboles, Git puede reconstruir exactamente lo que tenías y aplicarlo como una fusión a tres bandas. De ahí que los conflictos de stash pop sean conflictos de fusión normales y corrientes.

La pila, por su parte, es el reflog de refs/stash:

Eso explica de golpe tres cosas que antes parecían arbitrarias:

• Por qué la sintaxis es stash@{N}: es exactamente la sintaxis del reflog.
• Por qué los números se renumeran: son posiciones en un registro, no identificadores.
• Por qué se pueden recuperar stashes borrados: el objeto sigue en la base de datos hasta que pase el recolector de basura.

Y una consecuencia práctica muy útil: como el stash es un commit, puedes usar cualquier comando de commits con él.

Riesgo 1: el stash olvidado. Es, con diferencia, el problema más frecuente. Apartas algo, la urgencia se alarga, pasan tres semanas y el trabajo sigue ahí. Cuando lo encuentras, ya no encaja con nada.

El stash no aparece en git status, no aparece en git log, no sale en ninguna interfaz gráfica por defecto y no se envía nunca al servidor. Es invisible.

Medidas:

Y la medida real: el stash es para minutos u horas, no para días. Si el trabajo va a esperar más de una jornada, es una rama. git stash branch está justo para eso.

Riesgo 2: creer que es una copia de seguridad. No lo es, por tres motivos:

1. Es local. No se envía nunca con git push. El refspec por defecto solo cubre refs/heads/* (lección 04-05), y refs/stash queda fuera. Si se te muere el disco, el stash muere con él.
2. No se clona. git clone no trae los stashes de nadie. Ni siquiera un git clone --mirror los replica de forma útil.
3. Es frágil. git stash clear lo borra todo sin preguntar. Y los commits del stash, al no estar referenciados por ninguna rama, son candidatos al recolector de basura cuando se borran de la pila.

Una copia de seguridad de verdad es un commit en una rama publicada. Si el trabajo importa, confírmalo —aunque sea con un mensaje provisional que luego arreglarás con rebase -i (lección 05-02)— y publícalo.

Riesgo 3: aplicar el stash en la rama equivocada. El stash no está atado a una rama: puedes hacer pop en cualquiera. A veces es exactamente lo que quieres (moverte de rama con el trabajo a cuestas); a veces es un accidente que llena main de cambios que no le tocaban. git stash list te dice en qué rama se guardó cada entrada; léelo antes de recuperar.

Riesgo 4: los ficheros sin seguimiento. Ya lo vimos: sin -u no se guardan. El error concreto y peligroso es hacer git stash seguido de git clean -fd para "dejar todo limpio": el clean borra los ficheros sin seguimiento que el stash no guardó, y esos sí se pierden de verdad.

Error 1: git stash sin -u cuando hay ficheros nuevos. Se quedan fuera. Es la sorpresa número uno con esta herramienta. Mira siempre git status --short antes de apartar.

Error 2: git stash clear para "ordenar". Borra toda la pila sin preguntar y sin confirmación. Usa git stash drop <entrada> de una en una, después de mirar cada una con show -p.

Error 3: pensar que pop siempre elimina la entrada. Si hay conflicto, la conserva a propósito. Tras resolver, tienes que hacer git stash drop tú.

Error 4: acumular stashes sin mensaje. Cinco entradas llamadas WIP on main son cinco incógnitas. git stash push -m "..." siempre.

Error 5: usar el stash como sistema de ramas. Si vas a tardar más de una jornada, haz una rama. El stash no sobrevive a la memoria de nadie.

Error 6: fiarse de los números. stash@{2} cambia de significado en cuanto añades o quitas entradas. Identifica por mensaje, no por número.

Error 7: combinar git stash con git clean -fd sin pensar. El primero no guarda lo sin seguimiento; el segundo lo borra. La combinación destruye ficheros nuevos.

Consejo 1: alias con -u incorporado. git config --global alias.guardar 'stash push -u -m' y a partir de ahí git guardar "lo que sea".

Consejo 2: --keep-index antes de confirmar. Un git stash push --keep-index && npm test te dice si tu commit es realmente autocontenido. Se tarda un minuto y evita commits rotos.

Consejo 3: git stash show -p antes de pop. Especialmente si la entrada tiene más de un día. Saber qué va a llegar evita sustos.

Consejo 4: git stash branch en cuanto haya conflicto. No pelees con un pop que no encaja: crea la rama en el punto original, aplica limpiamente y fusiona con calma.

Consejo 5: revisa la pila los viernes. Un git stash list semanal es suficiente para que no se te quede nada tres meses.

En un repositorio de pruebas:

1. Modifica un fichero con seguimiento y crea uno nuevo sin añadir.
2. Haz git stash sin -u y comprueba con git status qué ha pasado con cada uno.
3. Recupera, y repite la operación con -u.
4. Demuestra con git stash show -p -u que en el segundo caso el fichero nuevo sí está dentro.

Prepara un escenario donde tengas dos cambios: uno preparado (que compila por sí solo) y otro sin preparar (que rompe el fichero). Usando --keep-index:

1. Aparta lo que no va en el commit.
2. Comprueba que el fichero es válido (node --check o similar).
3. Confirma.
4. Recupera el resto y observa qué pasa.

Crea un stash con -u y demuestra con comandos de bajo nivel:

1. Que refs/stash apunta a un commit.
2. Que ese commit tiene tres padres.
3. Qué contiene cada uno de los tres.
4. Que git reflog stash y git stash list muestran la misma información.

Solución 1:

seguido.txt ha vuelto a su versión original; sin-seguir.txt sigue exactamente donde estaba. No se ha guardado.

Ahora sí: el directorio está limpio de verdad y el fichero nuevo ha desaparecido (está en el stash).

Solución 2:

(El doble M significa: modificado en el índice y modificado además en el directorio de trabajo.)

El fichero contiene solo lo preparado.

El pop ha devuelto el estado completo que había antes. Como el commit ya contiene la línea de b, en este caso simple no hay conflicto; con cambios que se solapan en las mismas líneas sí lo habría, y es la razón por la que conviene revisar con git stash show -p antes.

Solución 3:

La misma información, presentada de dos formas. git stash list es, literalmente, una vista del reflog de refs/stash.

git stash es una herramienta pequeña con más matices de los que aparenta. Lo esencial:

• Aparta los cambios sin confirmar y deja el directorio limpio, para que puedas cambiar de rama, atender una urgencia o probar algo, y recuperarlos después.
• Por defecto NO guarda los ficheros sin seguimiento ni los ignorados: para eso están -u (sin seguimiento, la opción que querrás casi siempre) y -a (también los ignorados, que solo se usa muy conscientemente).
• Es una pila: git stash list la enumera, stash@{0} es la más reciente y los números se renumeran, así que hay que identificar por mensaje. git stash push -m "..." es obligatorio en la práctica.
• pop aplica y elimina; apply aplica y conserva. Si hay conflicto, pop conserva la entrada y tienes que hacer drop a mano tras resolver.
• --keep-index deja en el directorio solo lo que ibas a confirmar (para probarlo de verdad); --staged aparta solo lo preparado. Y push -p permite elegir trozo a trozo, y push <ruta> apartar solo unos ficheros.
• git stash branch <rama> crea una rama en el commit original del stash y lo aplica allí: la mejor salida cuando un stash ya no encaja.
• Por dentro no hay magia: son commits normales en refs/stash, con el HEAD original, el índice y los sin seguimiento como padres, y la pila es el reflog de esa referencia. De ahí vienen la sintaxis stash@{N} y la renumeración.
• No es una copia de seguridad: es local, no se envía, no se clona y clear lo borra sin preguntar. Para minutos y horas, no para días.

Hasta aquí, todo el módulo ha ido de modificar el historial: reaplicarlo, reorganizarlo, copiarlo, apartarlo. Ahora vamos a hacer lo contrario: fijar un punto en él para siempre.

gestor-tareas está a punto de tener su primera versión estable. El equipo necesita poder decir "esto es la 1.0.0" y que dentro de dos años, cuando llegue una incidencia de un cliente que sigue con esa versión, alguien pueda situarse exactamente en ese código sin depender de recordar un hash de cuarenta caracteres.

Para eso están las etiquetas, el cuarto tipo de objeto de la base de datos de Git que conocimos en la lección 01-04 y del que apenas hemos hablado. Lo vemos en la lección 05-05: Etiquetando Confirmaciones.