Si git pull falla mientras el proyecto de su Mac parece estar limpio, identifique primero el error exacto: Git podría estar protegiendo archivos locales o ignorados, ocultando cambios en submódulos o negándose a combinar historiales de ramas divergentes. En Terminal, inspeccione el estado completo del repositorio y el seguimiento de ramas antes de modificar archivos o elegir un comportamiento de merge o rebase.

Comience en el repositorio y capture el error real

Abra Terminal, sitúese en la carpeta del proyecto y vuelva a ejecutar el comando pull solo si necesita reproducir el mensaje. Terminal utiliza zsh de forma predeterminada en las versiones actuales de macOS, y los comandos entre comillas que figuran a continuación funcionan en zsh y bash. Guía de Terminal de Apple

cd "/path/to/your/project"
git status --short --branch
git pull

Reemplace la ruta entre comillas por la carpeta real de su proyecto. Lea el error completo de pull. «Your local changes … would be overwritten» apunta a una obstrucción a nivel de archivo. «Divergent branches» o «Not possible to fast-forward» significa que los historiales de commits locales y ascendentes (upstream) requieren una decisión de conciliación. Estos problemas pueden parecer similares en un cliente gráfico, pero exigen pasos diferentes.

Busque archivos ocultos por una vista de estado breve

Una vista resumida del estado puede omitir detalles importantes. Ejecute una inspección de solo lectura más exhaustiva:

git status --untracked-files=all --ignored=matching --ignore-submodules=none
git diff --
git diff --cached --

git status normalmente informa sobre archivos sin seguimiento (untracked), pero una configuración local puede ocultarlos; --untracked-files=all lista archivos individuales dentro de carpetas no rastreadas. Los archivos ignorados se excluyen a menos que se soliciten, por lo que --ignored=matching revela las rutas ignoradas que coinciden con las reglas de exclusión. --ignore-submodules=none indica a status que informe sobre cambios en submódulos incluso si la configuración normalmente los ocultaría. Git documenta estos modos de estado y señala que las rutas ignoradas reciben un marcador de estado distintivo. Documentación de Git status

Los dos comandos git diff muestran las modificaciones del árbol de trabajo con seguimiento y los cambios en el área de preparación (stage), respectivamente. No enumeran el contenido de archivos ignorados o sin seguimiento. Por lo tanto, un resultado «limpio» en una interfaz gráfica, en otra carpeta o en una vista de estado filtrada no garantiza que todas las obstrucciones sean visibles; use Terminal en el mismo repositorio e inspeccione la ruta exacta señalada por Git. Las reglas de ignore mantienen deliberadamente los archivos sin seguimiento coincidentes fuera de la salida de estado habitual. Documentación de Git ignore

Si la ruta indicada está ignorada o no tiene seguimiento, inspecciónela antes de moverla o eliminarla. No ejecute git clean, git reset --hard ni sobrescriba la ruta como atajo de diagnóstico: estos comandos pueden eliminar archivos o trabajo local. Si contiene algo que necesita, haga una copia aparte o consérvelo de otro modo antes de resolver el conflicto.

Revise los submódulos y las marcas del índice

Un repositorio con submódulos puede parecer limpio en su nivel superior mientras que un submódulo tiene ediciones locales, archivos sin seguimiento o un commit diferente descargado. El comando de estado ampliado anterior le pide a Git que no ignore el estado de los submódulos. También puede entrar en el directorio del submódulo en cuestión y ejecutar allí git status --untracked-files=all; cada submódulo tiene su propio árbol de trabajo y estado.

En un caso menos común, el índice de Git puede contener marcas (flags) que afectan la forma en que trata las rutas. assume-unchanged le indica a Git que asuma que un archivo coincide con el índice, y skip-worktree puede evitar que se actualice una ruta durante operaciones como pull. Inspeccione entradas inusuales con:

git ls-files -v

Esto lista las rutas rastreadas con etiquetas de índice; las etiquetas en minúsculas pueden indicar entradas con assume-unchanged, mientras que S indica skip-worktree. Tome esto como una pista de inspección, no como un comando de limpieza. No borre marcas a ciegas en todo el repositorio; si se señala una ruta afectada, revise su contenido y la configuración de sparse-checkout del proyecto antes de modificar el estado de su índice. Documentación de Git update-index

Si el mensaje trata sobre ramas divergentes

Un árbol de trabajo limpio no significa que su rama local y su rama ascendente tengan el mismo historial. Compruebe qué rama está activa y a cuál sigue:

git branch --show-current
git branch -vv
git status --short --branch

La salida de status y branch puede mostrar si la rama local va por delante, por detrás o si ha divergido de su upstream. Git pull primero descarga (fetch) los cambios remotos y luego integra el upstream configurado. Su comportamiento predeterminado de solo avance rápido (fast-forward-only) se detiene cuando las ramas local y remota han divergido; esto es una directiva de historial, no una prueba de cambios de archivos sin confirmar. Documentación de Git pull

Si existen commits locales, elija un método que se adapte a las reglas de colaboración del proyecto: rebase vuelve a aplicar los commits locales sobre el upstream, mientras que merge une los historiales y puede crear un commit de fusión. Consulte con los encargados del repositorio o la convención del equipo si no está seguro. Evite definir una preferencia global de pull o forzar el restablecimiento (force-reset) de la rama solo para silenciar el error; ninguna de estas acciones aclara qué debería suceder con esos commits.

Use el error para elegir la siguiente comprobación

Una colisión de archivos requiere revisar la ruta indicada, incluidos los archivos ignorados y los submódulos. Un mensaje de divergencia requiere inspeccionar el historial de ramas y decidir cómo integrar los commits. Si el estado sigue figurando limpio pero el error menciona una ruta, confirme que Terminal se encuentre en la copia de trabajo esperada, inspeccione esa ruta directamente y verifique si existen marcas de índice relevantes. El mensaje exacto es el diagnóstico más útil: conserve los archivos y commits locales hasta que comprenda qué tipo de rechazo está reportando Git.

Fuentes