How to fix error: unable to index file 'file.txt' in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 184 views

This error occurs when Git cannot add a file to its staging index. Common causes include file locks from other applications, permission issues, antivirus interference, or a corrupted index file. The fix usually involves closing programs that lock the file or resetting the Git index.

Quick fix

Fixes error: unable to index file 'file.txt'

# Check what processes might be using the file (Linux/macOS)
lsof <filename>

# On Windows, use Process Explorer or:
# Task Manager -> Details tab -> look for the application
  1. Close applications that may be locking the file
  2. Remove any stale index.lock file
  3. Temporarily disable antivirus real-time scanning
  4. Pause cloud sync services
git — error
# Check what processes might be using the file (Linux/macOS)
lsof <filename>
# On Windows, use Process Explorer or:
# Task Manager -> Details tab -> look for the application
error: unable to index file 'file.txt'

What this error means

When you run `git add`, Git attempts to update its index (also called the staging area) with information about the file you're adding. The index is stored in `.git/index` and tracks which files and changes will be included in your next commit. The "unable to index file" error means Git failed to write this information to the index. This can happen for several reasons: the file might be locked by another process (your IDE, antivirus, backup software), you might lack permission to write to the `.git` directory, the index file itself might be corrupted, or there might be an `index.lock` file left over from a crashed Git operation. This error blocks your ability to stage changes, which means you cannot commit until it's resolved. The good news is that your actual file contents are safe—only the staging operation failed.

Typical symptoms

  • Running 'git add <file>' fails with 'unable to index file' message
  • The error may specify 'Permission denied' as the reason
  • Git commands that modify the index (add, commit, reset) all fail
  • The problem may affect only specific files or all files in the repository
  • The error appears suddenly in a repository that was working fine before

Common causes

  1. The file is currently open in another application (IDE, editor, Excel) that locks it
  2. A previous Git operation crashed, leaving a stale .git/index.lock file
  3. Antivirus or backup software is scanning/locking the file or .git directory
  4. Insufficient permissions to write to the .git directory or the file itself
  5. Cloud sync services (Dropbox, Google Drive, OneDrive) interfering with Git operations
  6. The .git/index file is corrupted
  7. Disk space is full or nearly full
  8. On Windows, the file uses a reserved name (CON, PRN, AUX, NUL, COM1-9, LPT1-9)

How to fix "error: unable to index file 'file.txt'"

1Close applications that may be locking the file

The most common cause is another program holding a lock on the file. Close any applications that might have the file open:

bash
# Check what processes might be using the file (Linux/macOS)
lsof <filename>

# On Windows, use Process Explorer or:
# Task Manager -> Details tab -> look for the application

Common culprits:
- IDEs: VS Code, Visual Studio, JetBrains products
- Office applications: Excel, Word (especially for .xlsx, .docx files)
- Git GUIs: SourceTree, GitKraken, GitHub Desktop

After closing the application, retry your git add command.

2Remove any stale index.lock file

If a previous Git operation was interrupted (Ctrl+C, crash, power outage), it may have left behind a lock file:

bash
# Check if lock file exists
ls -la .git/index.lock

# If it exists and no Git process is running, remove it
rm .git/index.lock

On Windows:

cmd
del .git\index.lock

Important: Only remove this file if you're certain no other Git operation is running. Check for running Git processes first:

bash
# Linux/macOS
ps aux | grep git

# Windows (PowerShell)
Get-Process | Where-Object {$_.ProcessName -like "*git*"}
3Temporarily disable antivirus real-time scanning

Antivirus software can lock files during scanning, causing Git operations to fail. Try temporarily disabling real-time protection:

Windows Defender:
1. Open Windows Security
2. Go to Virus & threat protection
3. Click "Manage settings"
4. Toggle off "Real-time protection"

Better long-term solution: Add exclusions for your development directories:

bash
# Typical paths to exclude:
C:\Users\YourName\Projects\
C:\Users\YourName\Projects\**\.git\

Remember to re-enable protection after testing if this was the cause.

4Pause cloud sync services

If your repository is in a folder synced by Dropbox, Google Drive, OneDrive, or similar services, they may interfere with Git operations:

1. Pause syncing in the cloud sync application
2. Retry your Git operation
3. Resume syncing after the operation completes

Better approach: Move your Git repositories outside of cloud-synced folders. Use remote repositories (GitHub, GitLab) for backup instead.

bash
# Move repo out of synced folder
mv ~/Dropbox/my-project ~/Projects/my-project
cd ~/Projects/my-project
git add .
5Fix file and directory permissions

If the error mentions "Permission denied", you may need to fix ownership or permissions:

Linux/macOS:

bash
# Check current ownership
ls -la .git/

# Fix ownership (replace 'yourusername' with your actual username)
sudo chown -R $(whoami):$(whoami) .git/

# Ensure write permissions
chmod -R u+w .git/

Windows (run as Administrator):

cmd
icacls .git /grant %USERNAME%:F /T

Note: Avoid using sudo with Git commands, as it can create files owned by root that cause permission issues later.

6Reset the Git index

If the index file is corrupted, you can rebuild it from the last commit:

bash
# Make a backup first
cp .git/index .git/index.backup

# Remove the corrupted index
rm .git/index

# Rebuild from HEAD (last commit)
git reset

This recreates the index based on your last commit. Your working directory files remain unchanged, but you'll need to re-stage any changes you had previously staged.

Alternative using git read-tree:

bash
rm .git/index
git read-tree HEAD
7Use --ignore-errors flag as a workaround

If you need to add multiple files and only some are problematic, you can skip the errors:

bash
git add --ignore-errors .

This will add all files that can be added and report errors for the ones that fail, without aborting the entire operation.

Note: This is a workaround, not a fix. You should still investigate why specific files cannot be indexed.

8Check for Windows reserved filenames

On Windows, certain filenames are reserved and cannot be used, even in Git:

Reserved names: CON, PRN, AUX, NUL, COM1-COM9, LPT1-LPT9

If your file uses one of these names (e.g., aux.js, con.txt), you'll need to rename it:

bash
# Example: rename aux.js to auxiliary.js
git mv aux.js auxiliary.js

If the file was created on Linux/macOS and you're cloning on Windows, you may need to rename it on the original system or use WSL.

Advanced notes

### Understanding the Git Index

The Git index (.git/index) is a binary file that acts as a staging area between your working directory and the repository. When you run git add, Git:

1. Computes the SHA-1 hash of the file contents
2. Stores the file contents as a blob in .git/objects/
3. Updates the index with the file path, mode, and blob hash

The git update-index command provides lower-level access to index operations:

bash
# Refresh index with current file stat info
git update-index --refresh

# Force refresh, checking content changes
git update-index --really-refresh

# See what's in the index
git ls-files --stage

### Diagnosing Lock Issues

To find which process is locking a file:

Linux:

bash
lsof +D .git/
fuser .git/index

macOS:

bash
lsof .git/index

Windows (SysInternals Process Explorer):
1. Download Process Explorer from Microsoft
2. Go to Find -> Find Handle or DLL
3. Search for "index" or the filename

### TortoiseGit Icon Overlays

If you use TortoiseGit on Windows, the icon overlay feature can cause locking issues. To disable:

1. Right-click -> TortoiseGit -> Settings
2. Go to Icon Overlays
3. Set "Status cache" to "None"

### Git Configuration for Performance

If you frequently encounter indexing issues on large repositories, these settings may help:

bash
# Use file system monitor to reduce stat calls
git config core.fsmonitor true

# Enable untracked cache
git config core.untrackedCache true

# Split index for large repos
git update-index --split-index

### WSL2 Considerations

When using Git in WSL2 with files stored on the Windows filesystem (/mnt/c/...), you may experience more locking issues due to the filesystem translation layer. For best performance:

1. Keep repositories in the Linux filesystem (~/projects/)
2. Access Windows files only when necessary
3. Use git config core.autocrlf input to avoid line ending issues

Frequently asked questions

What does "error: unable to index file 'file.txt'" mean?
When you run git add, Git attempts to update its index (also called the staging area) with information about the file you're adding. git/index and tracks which files and changes will be included in your next commit. The "unable to index file" error means Git failed to write this information to the index.
How do I fix "error: unable to index file 'file.txt'"?
This error occurs when Git cannot add a file to its staging index. Common causes include file locks from other applications, permission issues, antivirus interference, or a corrupted index file. The fix usually involves closing programs that lock the file or resetting the Git index.
What causes "error: unable to index file 'file.txt'"?
The file is currently open in another application (IDE, editor, Excel) that locks it A previous Git operation crashed, leaving a stale .git/index.lock file Antivirus or backup software is scanning/locking the file or .git directory
Is the "error: unable to index file 'file.txt'" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading