This error occurs when Git detects a lock file indicating another Git process is running. Usually caused by an interrupted Git operation that left a stale .git/index.lock file behind. The fix is to safely remove the lock file after confirming no Git process is actually running.
This error means Git found a lock file (typically `.git/index.lock`) that prevents it from running. Git uses lock files to ensure only one process can modify the repository's index at a time, preventing data corruption from concurrent operations. When you perform Git commands like `git add`, `git commit`, or `git pull`, Git creates a temporary lock file to signal that the repository is being modified. Once the operation completes successfully, Git removes this lock automatically. However, if a Git process is interrupted (by a crash, power failure, forceful termination, or system hang), the lock file can be left behind as an "orphan." The full error message typically looks like: ``` fatal: Unable to create '/path/to/repo/.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. ```
Before removing any lock files, verify no Git process is actually running:
On Linux/macOS:
# List all running Git processes
ps aux | grep git
# If you find processes that should be terminated:
kill <PID>
# Or force kill if necessary
kill -9 <PID>On Windows (Command Prompt):
tasklist | findstr gitOn Windows (PowerShell):
Get-Process | Where-Object { $_.Name -like "*git*" }If you find Git processes running that you don't recognize, wait for them to complete or investigate what triggered them before terminating.
Once you've confirmed no Git processes are running, remove the stale lock file:
On Linux/macOS:
rm -f .git/index.lockOn Windows (Command Prompt):
del .git\index.lockOn Windows (PowerShell):
Remove-Item .git\index.lock -ForceThe -f flag (or -Force) prevents errors if the file doesn't exist.
Sometimes other lock files can cause similar issues. Check for and remove these if present:
# Check for HEAD lock
ls -la .git/HEAD.lock
# Check for branch-specific locks
ls -la .git/refs/heads/*.lock
# Remove if they exist and no Git process is running
rm -f .git/HEAD.lock
rm -f .git/refs/heads/*.lockFind all lock files in the repository:
find .git -name "*.lock" -type fRemove any stale lock files you find:
find .git -name "*.lock" -type f -deleteAfter removing the lock file(s), retry the command that failed:
# Whatever command you were trying to run
git status
git add .
git commit -m "Your message"
git pull
git pushIf the command works, the issue is resolved. If you still get the same error, there may be another process holding the lock or another lock file you missed.
If the problem persists or recurs, check for applications that might be using Git in the background:
Common culprits:
- VS Code - Has built-in Git integration that runs automatically
- GitKraken, Sourcetree, GitHub Desktop - Git GUI clients
- JetBrains IDEs (IntelliJ, PyCharm, etc.) - Have Git integration
- Git hooks - Custom scripts that might spawn processes
- File sync services - Dropbox, OneDrive, Google Drive in Git directories
Temporarily disable IDE Git features:
- VS Code: Set "git.enabled": false in settings
- Close all Git GUI applications before running commands
Check for and close background processes:
# macOS
pkill -f "git"
# Linux
killall git
# Be careful - this kills ALL git processesIf you still have issues, try these additional steps:
Restart your terminal:
Sometimes terminal sessions hold onto file handles. Close and reopen your terminal.
Restart your computer:
A reboot clears all processes and releases all file locks.
Check file permissions:
# Ensure you own the lock file
ls -la .git/index.lock
# If owned by another user, you may need sudo
sudo rm -f .git/index.lockCheck for network file system issues:
If your repository is on a network drive (NFS, SMB), lock files can behave unexpectedly. Consider cloning to a local drive.
Verify repository integrity:
git fsck### Understanding Git's Locking Mechanism
Git uses an atomic file creation approach for locking. When Git starts a write operation:
1. It creates the lock file using O_EXCL flag (exclusive create)
2. Writes changes to the lock file
3. Renames the lock file to the actual file (atomic operation)
4. If Git dies, an atexit() handler attempts cleanup
The lock file serves two purposes:
- Mutual exclusion: Prevents concurrent modifications
- Atomic writes: Changes are staged in the lock file before being committed
### Lock File Types
| File | Purpose |
|------|---------|
| .git/index.lock | Protects the staging area (index) |
| .git/HEAD.lock | Protects HEAD pointer updates |
| .git/refs/heads/<branch>.lock | Protects branch reference updates |
| .git/config.lock | Protects config file modifications |
| .git/COMMIT_EDITMSG.lock | Protects commit message editing |
### Why Lock Files Become Stale
Lock files become orphaned when Git can't clean up after itself:
- SIGKILL (kill -9): No chance to run cleanup handlers
- Power failure: No graceful shutdown
- System crash: OS-level failure
- Disk full: Can't complete the operation or cleanup
- NFS stale handles: Network filesystem issues
### Preventing This Issue
1. Don't use kill -9 on Git: Use regular kill or Ctrl+C and wait
2. Let Git operations complete: Don't close terminals mid-operation
3. Avoid concurrent Git access: Don't run multiple Git commands simultaneously
4. Keep repositories on local drives: Avoid NFS/network drives when possible
5. Use Git's built-in timeout: Long operations should complete or fail gracefully
### CI/CD Considerations
In CI/CD pipelines, this error often indicates:
- Previous build failed and left locks behind
- Parallel jobs accessing the same workspace
- Workspace not properly cleaned between runs
Solutions:
# GitLab CI example - clean workspace
before_script:
- rm -rf .git/index.lock .git/*.lock .git/refs/heads/*.lock 2>/dev/null || true
# GitHub Actions - use fresh checkout
- uses: actions/checkout@v4
with:
clean: true### Scripting Safe Lock Removal
For automated environments, use a script that checks for processes first:
#!/bin/bash
REPO_PATH="${1:-.}"
LOCK_FILE="$REPO_PATH/.git/index.lock"
if [ -f "$LOCK_FILE" ]; then
if pgrep -f "git" > /dev/null; then
echo "Warning: Git processes are running. Not removing lock."
exit 1
else
rm -f "$LOCK_FILE"
echo "Removed stale lock file"
fi
fiwarning: BOM detected in file, this may cause issues
UTF-8 Byte Order Mark (BOM) detected in file
fatal: Server does not support --shallow-exclude
Server does not support --shallow-exclude
warning: filtering out blobs larger than limit
Git partial clone filtering large blobs warning
fatal: Server does not support --shallow-since
Server does not support --shallow-since in Git
kex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server