Git: Unable to create '.git/index.lock': File exists

Ejecutas git add, git commit, git checkout o git merge y Git se detiene con este mensaje:

fatal: Unable to create 'C:/proyectos/mi-app/.git/index.lock': File exists.

Another git process seems to be running in this repository, or the lock file may be stale

En versiones anteriores de Git el texto es más largo, pero dice lo mismo:

fatal: Unable to create '/home/usuario/mi-app/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again. If it still fails, a git process
may have crashed in this repository earlier:
remove the file manually to continue.

Este artículo explica qué es ese archivo, cómo distinguir un bloqueo huérfano de uno legítimo y cómo eliminarlo con seguridad en Windows, Linux o WSL.

Por qué pasa

Antes de modificar un archivo importante del repositorio, como el índice (el área de preparación o staging), Git crea junto a él un archivo con el mismo nombre y la extensión .lock. Según la documentación técnica de Git, el archivo de bloqueo se crea con la bandera O_CREAT|O_EXCL, es decir, la creación falla si ya existe. Git escribe en él el contenido nuevo y, al terminar, lo renombra al nombre original. Mientras tanto, quien solo lee sigue viendo el contenido anterior.

La documentación también explica que Git elimina sus archivos de bloqueo al salir, incluso cuando termina con un error o por una señal que puede capturar. Si ves el error, hay dos explicaciones posibles:

  • Otro proceso de Git está trabajando de verdad. Puede ser un IDE que consulta el estado en segundo plano, una interfaz gráfica de Git, un script o un comando tuyo en otra terminal. La documentación de git status advierte que, por defecto, escribe el índice refrescado y que ese bloqueo puede hacer fallar a otros procesos simultáneos. También un comando lento puede mantener el bloqueo: en una prueba con Git 2.54 para Windows, un git commit -a con un hook pre-commit de unos segundos mantuvo .git/index.lock mientras el hook corría, y un git add lanzado en ese lapso falló con este mismo error. Al terminar el hook, el archivo desapareció.
  • El bloqueo quedó huérfano. Si un proceso de Git se interrumpe de forma abrupta (cierre forzado, apagado del equipo, fallo del sistema), no llega a limpiar su archivo. El propio mensaje lo menciona: a git process may have crashed in this repository earlier.

Observa que no todos los comandos fallan: con un index.lock presente, git status siguió funcionando en la prueba, porque la escritura del índice que hace es opcional.

Solución

  1. Identifica el archivo exacto. La ruta aparece en el mensaje. En un repositorio normal es .git/index.lock; en un worktree adicional (git worktree add) está en una carpeta propia dentro de .git/worktrees/. Para ver la ruta correcta desde cualquier carpeta del repositorio:

    git rev-parse --git-path index.lock
  2. Comprueba si hay realmente un proceso de Git en ejecución. En Linux, macOS o WSL:

    pgrep -a git

    En PowerShell:

    Get-Process git -ErrorAction SilentlyContinue

    (En el Administrador de tareas también puedes buscar git.exe.) Revisa además si tu editor o una herramienta gráfica de Git está haciendo una operación. Si hay un proceso activo, espera a que termine o ciérralo de forma normal, y vuelve a intentarlo. No borres el archivo mientras alguien lo está usando.

  3. Si no hay ningún proceso de Git, borra el archivo. En Bash:

    rm -f .git/index.lock

    En PowerShell, desde la raíz del repositorio:

    Remove-Item .git\index.lock

    El archivo de bloqueo solo contiene la actualización a medio escribir, no tus datos: el índice original sigue intacto hasta que Git hace el renombrado final. Al borrar un bloqueo huérfano solo pierdes una actualización que nunca se completó.

  4. Repite el comando que falló. Por ejemplo, git add ., git commit o git merge. Si el error vuelve a aparecer enseguida, hay un proceso que lo recrea: vuelve al paso 2 y revisa herramientas en segundo plano.

Cómo verificar que quedó resuelto

git status
git fsck --no-dangling
git log --oneline -3

git status debe mostrar el estado sin errores. git fsck verifica la conectividad y la validez de los objetos de la base de datos del repositorio; con --no-dangling omite la lista de objetos sin referencia. En la prueba no mostró salida y terminó con código de salida 0. git log confirma que HEAD apunta al último commit esperado. En PowerShell, Test-Path .git\index.lock debe devolver False.

En la reproducción local (un bloqueo vacío creado a mano, sin ningún proceso de Git activo), tras borrar el archivo el git add y el git commit pendientes se completaron y git fsck --no-dangling terminó con código 0.

Variantes y errores relacionados

Otros archivos de bloqueo: HEAD.lock, referencias y configuración

El mismo mecanismo protege otros archivos. Con un bloqueo presente, estos fueron los mensajes en la prueba:

fatal: cannot lock ref 'HEAD': Unable to create '.../.git/HEAD.lock': File exists.
fatal: cannot lock ref 'HEAD': Unable to create '.../.git/refs/heads/master.lock': File exists.
error: could not lock config file .git/config: File exists

La solución es la misma: confirma que no hay procesos de Git activos y borra únicamente el archivo .lock que menciona el mensaje.

Un mensaje con el número de proceso

En el código fuente más reciente de Git (rama principal), el mensaje puede incluir textos como Lock may be held by process seguido de un identificador de proceso. Si lo ves, comprueba ese identificador antes de borrar nada.

Herramientas que consultan el estado en segundo plano

Si tu editor o un script ejecuta git status continuamente, puede provocar este error en tus comandos. La documentación recomienda que los procesos en segundo plano usen:

git --no-optional-locks status

Es equivalente a definir la variable de entorno GIT_OPTIONAL_LOCKS=0: Git completa la operación sin las tareas opcionales que requieren un bloqueo, como refrescar el índice.

Hooks lentos

Si el bloqueo aparece siempre durante un git commit con hooks que ejecutan compilaciones o pruebas, el comando de Git es el que está en marcha: espera a que termine el hook antes de lanzar otro comando en ese repositorio.

Varios worktrees

Cada worktree tiene su propio index.lock. En la prueba, un index.lock en el repositorio principal no impidió un git add en un worktree adicional.

Resumen

  • index.lock es el archivo temporal con el que Git protege la actualización del índice; si ya existe, Git se niega a continuar.
  • Puede ser un proceso de Git legítimo (IDE, script, hook lento) o un bloqueo huérfano de un proceso interrumpido.
  • Comprueba primero los procesos (pgrep -a git o Get-Process git); si hay uno activo, espera.
  • Si no hay ninguno, borra solo ese archivo (rm -f .git/index.lock o Remove-Item .git\index.lock) y repite el comando.
  • Para herramientas en segundo plano, usa git --no-optional-locks status; verifica con git status y git fsck --no-dangling.

Referencias

Comentarios