That error means Git (or whatever tool is emitting it) found a lock file — usually .git/index.lock — left inside the repository, and it refuses to modify the repository's state while that file exists to prevent two writers from corrupting the index at the same time. The file is a mutual-exclusion marker, not corruption itself. Deleting it fixes the message, but only after you confirm no process is still writing.
The message is the software equivalent of a bathroom door with a sign on the knob. Someone set the sign to "occupied" before entering, and the sign never came down. The door is not broken. Either someone is still inside, or they left without flipping the sign. Almost all of the diagnosis is figuring out which.
The mechanism: an advisory lock on a mutable index
Git's staging area is a single binary file, .git/index. It records every tracked path, its blob hash, its stat data, and flags. Every git add, git commit, git checkout, git stash, and git merge rewrites that entire file. Rewriting a large binary file in place is not atomic: a crash midway leaves a half-written index, and two concurrent writers interleave garbage.
Git's answer is a lock-and-rename pattern. Before touching the index, it creates .git/index.lock with an exclusive create operation (O_CREAT | O_EXCL), which fails if the file already exists. The writer does its work on a temporary copy, then renames the temporary over index and deletes the lock. On POSIX systems a rename is atomic, so readers see either the old index or the new one, never a torn one. If Git cannot create the lock, it prints the message and exits without modifying anything.
Two details inside that mechanism matter. First, the lock carries the creating process's PID, and on most platforms that number is the basis for Git's staleness heuristic when you reuse the same checkout. Second, the exclusion is advisory in spirit but enforced in practice: it does nothing to files outside .git, so your working-tree files can still be edited while the lock is held. The lock only guards Git's own bookkeeping.
The same pattern appears far beyond the index. Package managers write package-lock.json, poetry.lock, Cargo.lock, and Pipfile.lock as resolved dependency snapshots, and they hold temporary lock files while resolving. Configuration tools use .lock siblings. A "lock file already exists" message can therefore come from four distinct followers of one pattern, and each has its own remediation.
Quantified context: what the lock costs and where it appears
The cost is almost always time, not data. In a typical workflow the lock is transient and lives for milliseconds to a few seconds. The exception is a long-running Git process: an interactive rebase, a git gc, or a commit that hooks have stalled. Some repositories use Git LFS, and its file locking for binary assets is a separate, user-facing feature; the repository-lock message is not that.
Red flag: a lock file appearing and disappearing repeatedly on its own. That points to two automated processes racing, such as a file-watcher triggering commits while an editor autosaves. Red flag: Git reporting a lock on almost every command. Look for a GUI client or IDE plugin holding the index. Red flag: the lock file is not empty and its timestamp is recent, seconds old. Something is writing right now. Red flag: a post-commit or pre-commit hook that invokes Git recursively. The inner call waits on a lock the outer one owns.
The bounds are worth stating plainly: if no process holds it and you are on a local filesystem, removal is immediate and harmless. On network shares, the analysis changes (see the limitations section).
Failure modes and edge cases
Most cases fall into five buckets. The first is a crashed or killed process: the PID is gone, the file remains. A laptop that sleeps mid-commit, a CI runner killed at its timeout, and a terminal closed during a rebase all leave orphans. The second is a still-running process, which is common with GUI clients. The third is stale information: the lock you are fighting lives in a different clone or a linked worktree.
Linked worktrees are the counterintuitive case. In a multi-worktree repository, Git stores per-worktree data under .git/worktrees//, and each worktree can have its own index lock. Deleting the lock in your current worktree will not clear an error raised by another. Similarly, a bare repository used as a remote can show lock errors on concurrent pushes; that is server-side state, not a local problem.
The fourth bucket is permissions and ownership. A sudo git command creates .git/index.lock owned by root. Your normal user cannot unlink it, so the error persists after the process exits. The fix is ownership repair, not blind deletion with rm that may be blocked. The fifth is the non-Git followers: a dependency resolver reporting an existing lock, or a configuration framework in a parent directory whose lock cascades into every project beneath it.
Misconceptions: what the lock is not, and what deletion breaks
| Symptom or belief | What the lock actually is | Safe action |
|---|---|---|
| "The repo is corrupted" | An ordinary file owned by Git's bookkeeping | Inspect, do not assume damage |
| "Deleting the lock loses commits" | The lock is empty or a partial temporary; commits live in objects | Verify no process, then delete |
| "Another clone's lock blocks me" | Locks are per-repository-path, not global | Work in the right clone |
| "The package lock is the same thing" | Dependency snapshot, not an exclusion marker | Resolve dependencies, do not delete |
| "Killing Node fixes the Git lock" | Unrelated processes cannot create .git locks | Identify the actual Git process |
| "Git LFS locks are this error" | LFS locking is a separate feature for binaries | Manage LFS locks explicitly |
The most consequential misconception is that the lock protects your work. It does not; it protects the consistency of the index. Deleting a live lock does not corrupt existing commits, which are immutable objects addressed by hash. What it can do is let two writers race, which can leave a staged state that reflects neither operation cleanly. That risk is small but real, so the order of operations is always identify, then delete.
Practical actions with concrete thresholds
The procedure needs about five commands and one judgment call.
Identify the path and lock: run git status to confirm the repository root, then list lock files inside .git and any linked worktree's admin directory. Check for a holder: on Linux and macOS, use lsof .git/index.lock; on Windows, use a handle-inspection tool. No output means no open file handle. Check recency: a lock older than a few minutes with no holder is stale with high confidence. A lock seconds old deserves caution. Remove only after steps two and three agree: delete the lock file, then confirm with git status before any further write. For permission errors, repair ownership of the repository rather than elevating the next Git command; running Git as another user is the cause, not the cure. For dependency lock files: run the resolver's install or sync command; if it still reports a lock, treat it as a configuration issue and inspect the lock directory it names.
Reconciling thresholds: three signals are in play. Hold-time (seconds), holder existence (binary), and ownership (binary). Delete when all three are inconsistent with a live process; investigate when any one is consistent. The rule of thumb: if you cannot name the process, do not guess — inspect first.
Limits, and when a "lock" is something else
The absence of a holder does not guarantee a stale lock forever. On network filesystems (NFS, SMB, cloud-synced folders) lock semantics can be unreliable: advisory locks may not be honored, and delete operations may lag. File watchers can also recreate the file immediately after deletion, making it look as though it was never removed. If a lock reappears within seconds of deletion, stop deleting and find the writer.
Finally, lock files can be evidence useful for after-the-fact debugging. Their presence and timestamps tell you when a process died and roughly what it was doing. Deleting immediately throws that evidence away. Copy the file, note its timestamp and size, then remove it.
The operational rule is simple and protective: confirm no process is writing, inspect before deleting, and never treat a lock file as proof of corruption.