git restore

Qué hace git restore

El comando git restore copia una versión limpia de un archivo en tu árbol de trabajo, en tu área de preparación (staging) o en ambos. Introducido en Git 2.23 junto con git switch, asumió las funciones a nivel de archivo que antes estaban enterradas dentro del sobrecar­gado comando git checkout. Su propósito es responder una pregunta: ¿de dónde debe venir la copia correcta de este archivo y adónde debe ir?

Para usarlo correctamente, conviene conocer los "tres árboles" de Git: el árbol de trabajo (los archivos que editas en disco), el índice (también llamado área de preparación — lo que git add escribe y lo que capturará el siguiente commit), y HEAD (la instantánea de tu último commit). git restore siempre mueve contenido desde un origen hacia un destino entre estos. Dos opciones controlan eso:

• --source=<rev> — de dónde proviene la copia limpia. Por defecto es el índice, o HEAD cuando se usa --staged.
• --staged y/o --worktree — dónde se escribe la copia. Por defecto es --worktree.

Esta página cubre los usos cotidianos: descartar ediciones, desagregar archivos, restaurar desde un commit anterior, recuperar un archivo eliminado y en qué se diferencia restore de reset y revert.

Descartar cambios del árbol de trabajo

Por defecto, git restore sobreescribe un archivo en tu directorio de trabajo con la versión del área de preparación (el índice). Si has editado un archivo y quieres descartar esas ediciones:

git restore index.html

El archivo vuelve a su último estado preparado (o a su estado en HEAD si nunca fue preparado). Dado que esta operación es destructiva — tus ediciones no preparadas desaparecen de forma permanente y no pueden recuperarse con git reflog — Git le da deliberadamente un nombre claro y explícito en lugar de esconderla detrás de checkout.

Para descartar cambios en muchos archivos a la vez, pasa un directorio o un pathspec. Este es uno de los pocos comandos de git restore que puede borrar mucho trabajo de un solo teclazo, así que comprueba primero qué está sin confirmar con git status:

git restore .          # discard all changes in the current directory
git restore src/       # discard all changes under src/

Desagregar con --staged

Para quitar un archivo del área de preparación sin cambiar su contenido en disco, usa --staged. Esto copia la versión de HEAD de vuelta al índice, dejando intactas las ediciones de tu árbol de trabajo:

git restore --staged index.html

Este es el reemplazo moderno de git reset HEAD <file>, y es exactamente lo que Git sugiere en su texto de ayuda cuando ejecutas git status después de preparar algo:

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html

Restaurar desde un commit específico

La opción --source te permite extraer el contenido de un archivo desde cualquier commit, rama o etiqueta — no solo desde el índice o HEAD:

git restore --source=HEAD~2 config.yml

Esto rebobina un único archivo a como lucía dos commits atrás. Ten en cuenta lo que no hace: no crea un commit ni mueve ningún puntero de rama. El contenido antiguo llega a tu árbol de trabajo como un cambio normal sin preparar, listo para que lo inspecciones, prepares y confirmes tú mismo. Puedes usar el nombre de una rama (--source=main) o una etiqueta (--source=v1.0) con igual facilidad.

Recuperar un archivo eliminado

Si eliminas por error un archivo rastreado y aún no has confirmado la eliminación, git restore lo recupera desde el índice o HEAD:

git restore app.js

Dado que el archivo sigue existiendo en una instantánea conocida, Git lo vuelve a escribir en disco exactamente como estaba. (Si ya confirmaste la eliminación, restáuralo desde antes de ese commit: git restore --source=HEAD~1 app.js.)

Restablecer ambas copias a la vez

Combinar --staged y --worktree restablece un archivo por completo — tanto la copia preparada como la copia en disco — de vuelta a HEAD:

git restore --staged --worktree index.html

Este es el comando "haz que este archivo luzca exactamente como el último commit, sin importar lo que haya hecho". Descarta tanto las ediciones preparadas como las no preparadas en un solo paso.

Restaurar parte de un archivo

Al igual que git add y git checkout, git restore admite un modo de parche. Con -p (o --patch), Git te guía por cada bloque de cambio y te pregunta si descartarlo, de modo que puedas eliminar algunas ediciones y conservar otras:

git restore -p index.html

Esto es útil cuando has realizado varios cambios no relacionados en un archivo y solo quieres deshacer un experimento específico.

Opciones comunes

restore vs reset vs revert

Estos tres comandos son fáciles de confundir porque todos "deshacen" algo, pero funcionan en distintos niveles:

• git restore opera sobre archivos en el árbol de trabajo y el índice. Nunca mueve punteros de rama ni reescribe el historial.
• git reset mueve la punta de la rama actual y puede cambiar el área de preparación — opera a nivel de commit.
• git revert crea un nuevo commit que deshace uno anterior, dejando intacto el historial existente.

Usa restore cuando simplemente quieras que un archivo luzca como lo hacía en otro lugar. Si deseas eliminar commits completos o mover una rama, ese es el trabajo de git reset. Si los cambios ya han sido enviados y compartidos, usa git revert para no reescribir el historial del que otros dependen. Para apartar cambios temporalmente en lugar de descartarlos, consulta git stash.

Práctica