git add

Descripción

El comando git add añade los cambios del directorio de trabajo al área de preparación (también llamada índice). Con él, le indicas a Git qué cambios de archivo deseas incluir en el próximo commit. git add no guarda nada en el historial por sí solo — solo marca los cambios como listos. Para registrarlos definitivamente, debes ejecutar git commit a continuación. Para inspeccionar qué está preparado y qué no en cualquier momento, usa git status.

Esta página explica qué hace git add, las tres "áreas" de Git entre las que actúa, sus opciones más útiles, y los modos interactivo y de edición de parches para preparar cambios fragmento por fragmento.

Las tres áreas

Todo cambio en un proyecto Git pasa por tres áreas:

• Directorio de trabajo — los archivos que realmente editas en disco.
• Área de preparación (índice) — una instantánea de lo que irá en el próximo commit.
• Repositorio — el historial de commits, escrito por git commit.

git add mueve los cambios del directorio de trabajo al área de preparación. git commit luego escribe lo que está preparado en el repositorio. Este flujo en dos pasos es lo que permite dividir un directorio de trabajo desordenado en commits limpios y enfocados.

¿Por qué preparar los cambios?

En muchos sistemas de control de versiones, al hacer un commit se registra todo lo que cambiaste. Git añade deliberadamente el área de preparación en medio para que puedas decidir exactamente qué contiene cada commit. Esto es útil cuando has editado varias cosas no relacionadas a la vez: puedes preparar y confirmar un cambio lógico, luego preparar y confirmar el siguiente, manteniendo tu historial legible.

Dado que la preparación captura una instantánea en el momento en que la ejecutas, git add debe ejecutarse de nuevo cada vez que hagas ediciones adicionales que quieras incluir. Si preparas un archivo y luego sigues editándolo, las ediciones posteriores permanecerán sin preparar hasta que ejecutes git add una vez más.

Opciones comunes

Preparar un único archivo para el próximo commit:

git add <file>

Preparar todos los cambios dentro de un directorio (de forma recursiva, incluyendo archivos nuevos):

git add <directory>

Preparar todos los cambios en todo el repositorio — archivos nuevos, modificados y eliminados:

git add -A

Preparar cambios en archivos ya rastreados solamente, incluidas las eliminaciones, pero ignorar archivos nuevos sin seguimiento:

git add -u

Preparar cambios de forma interactiva, eligiendo partes de archivos fragmento por fragmento:

git add -p

git add . vs git add -A vs git add -u

Estos tres son fáciles de confundir, por lo que vale la pena ser precisos:

En versiones modernas de Git, tanto git add . como git add -A preparan las eliminaciones; la diferencia es únicamente el alcance de la ruta. Usa -u cuando hayas creado archivos desechables que no deseas confirmar y prefieras no listarlos en .gitignore.

Ejemplos de git add

Puedes ejecutar estos comandos en cualquier repositorio Git. Comienza comprobando el estado actual con git status, luego prepara y confirma los cambios.

Preparar un archivo nuevo

git add hello.py

Preparar varios archivos específicos a la vez

git add hello.py utils.py README.md

Preparar todo y luego confirmar con un mensaje

git add -A
git commit -m "Add greeting script"

Ver qué está preparado antes de confirmar

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   hello.py

Para sacar un archivo del área de preparación sin perder tus ediciones, usa git restore --staged (o, en versiones antiguas de Git, git reset):

git restore --staged hello.py

Modo interactivo

Ejecutar git add -p (o elegir la opción de parche desde git add -i) inicia una sesión de preparación interactiva. Git te muestra un fragmento — un bloque de líneas modificadas — a la vez y solicita un comando. Las respuestas más comunes son:

• y - preparar este fragmento
• n - no preparar este fragmento
• q - salir; no preparar este fragmento ni los restantes
• a - preparar este fragmento y todos los siguientes en el archivo
• d - no preparar este fragmento ni los siguientes en el archivo
• g - seleccionar un fragmento al que ir
• / - buscar un fragmento que coincida con la expresión regular dada
• j - dejar este fragmento sin decidir, ir al siguiente fragmento sin decidir
• J - dejar este fragmento sin decidir, ir al siguiente fragmento
• k - dejar este fragmento sin decidir, ir al fragmento anterior sin decidir
• K - dejar este fragmento sin decidir, ir al fragmento anterior
• s - dividir el fragmento actual en fragmentos más pequeños
• e - editar manualmente el fragmento actual
• ? - mostrar ayuda

Dividir (s) es especialmente útil: si Git presenta dos ediciones no relacionadas como un solo fragmento, s las separa para que puedas preparar solo la parte que deseas. Esta es la manera habitual de construir un commit limpio a partir de un archivo con cambios mixtos.

Edición de parches

Llamar a git add -e o seleccionar e en el selector interactivo de fragmentos abre un parche en tu editor. Al salir del editor, el resultado se aplica al índice. Puedes hacer cambios arbitrarios en el parche, pero algunas ediciones pueden generar resultados complejos o incluso hacer que el parche no sea aplicable. Si deseas cancelar la operación por completo, simplemente elimina todas las líneas del parche. A continuación se muestran algunos elementos comunes que puedes ver en un parche y qué operaciones de edición tienen sentido para ellos.

Las líneas que comienzan con + representan contenido añadido. Puedes eliminarlas para evitar que se preparen las líneas añadidas.

Las líneas que comienzan con - representan contenido eliminado. Para evitar preparar su eliminación, puedes convertir el - en un espacio ( ).

El contenido modificado se muestra con líneas - (eliminando el contenido antiguo) seguidas de líneas + (añadiendo el contenido de reemplazo). Para evitar preparar la modificación, convierte las líneas - en espacios y elimina las líneas +. Ten en cuenta que modificar solo la mitad del par puede causar cambios confusos en el índice.

Problemas frecuentes

• La preparación es una instantánea, no un enlace en vivo. Si haces git add en un archivo y luego lo editas de nuevo, solo la versión anterior queda preparada. Ejecuta git add una vez más para incluir las nuevas ediciones — git status mostrará el mismo archivo tanto en "Cambios a confirmar" como en "Cambios no preparados para confirmar".
• git add no elimina archivos por ti. Prepara las eliminaciones de archivos ya rastreados (con -A o -u), pero para eliminar un archivo del disco y preparar esa eliminación en un solo paso, usa git rm.
• Los archivos ignorados permanecen ignorados. Los patrones en .gitignore no son preparados por git add .. Para forzar la adición de un archivo ignorado, usa git add -f <file>.
• Nada es permanente aún. La preparación es completamente reversible. Usa git restore --staged <file> para deshacer la preparación antes de confirmar.

Práctica