Victor's room

Overview & Root Cause Summary: The error fatal: Unable to create '.git/index.lock': File exists occurs when Git attempts to perform an operation modifying the repository’s index or staging area (such as git add, git commit, git checkout, or git merge) while an index.lock file is already present. Git creates this lock file as a concurrency control mechanism to prevent simultaneous processes from corrupting the repository index. When a previous Git process crashes, is forcefully killed, or an IDE file-watcher holds a background lock, the file remains orphaned and prevents any further Git operations.

Understanding the Root Causes

• Crashed or Forcefully Killed Git Process: A terminal window was terminated during an active command, or a machine reboot occurred before Git could cleanly remove the temporary lock file.
• IDE and Background Extension Conflicts: Code editors like VS Code, JetBrains IDEs, or Git GUI clients executing background polling (e.g., auto-fetch, linting extensions) simultaneously with manual CLI operations.
• Cloud Sync / Network Drive Latency: Hosting repositories inside Dropbox, OneDrive, iCloud, or network file systems (NFS/SMB) that delay or interfere with file deletion and atomic locking.
• Active Interactive Commands: An uncompleted interactive rebase (git rebase -i) or an open Git editor session waiting for commit messages in another terminal tab.

Step 1: Quick Fix (Audit Running Processes and Remove the Stale Lockfile)

Before deleting the lockfile, ensure no legitimate Git background process is still actively writing data to avoid index corruption.

# 1. Check for any active background Git processes (Linux/macOS):
ps aux | grep -i git | grep -v grep

# On Windows (PowerShell):
Get-Process -Name *git* -ErrorAction SilentlyContinue

# 2. Terminate hung Git processes if necessary:
killall -9 git   # Linux/macOS
# Stop-Process -Name git -Force  # Windows PowerShell

# 3. Safely delete the orphaned lock file:
rm -f .git/index.lock

# On Windows PowerShell:
Remove-Item -Force .git\index.lock

Step 2: Resolving Submodule Lockfiles and Lock File Variants

In repositories with Git submodules or during operations like rebasing or branching, lock files can be generated in deeper directories or under different names.

# 1. Search for all lock files inside the .git directory:
find .git/ -name "*.lock"

# 2. If working with submodules, remove any stuck locks in the modules directory:
rm -f .git/modules/**/index.lock

# 3. Clean up HEAD or ref-specific lockfiles if rebase/checkout stalled:
rm -f .git/HEAD.lock
rm -f .git/refs/heads/*.lock

Step 3: Preventing Recurrence (IDE & Cloud Drive Configuration)

Prevent future locking collisions by configuring IDE auto-fetch behavior and excluding repository directories from real-time cloud synchronizers.

# Option A: Disable aggressive auto-fetching in VS Code (settings.json):
# "git.autofetch": false,
# "git.autorefresh": true

# Option B: Verify and refresh the repository staging index if it was left in an inconsistent state:
git reset HEAD

Verification & Testing Steps

Confirm that the lock file has been cleanly cleared and repository operations proceed without interruption.

# 1. Confirm that no lock files remain in .git:
ls -la .git/index.lock

# 2. Check working tree status:
git status

# 3. Perform a test stage and commit to ensure index integrity:
git add .
git status

Summary Comparison Table