Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Environment Variables

GIT_OPTIONAL_LOCKS

Reference for GIT_OPTIONAL_LOCKS and git --no-optional-locks: stop read-only commands such as git status from taking index locks that clash with other Git operations.

Some Git commands that look read-only still write. git status is the famous case: if it finds that a file's timestamp changed but its content did not, it updates the cached stat data in .git/index so the next run is faster. To do that safely it takes index.lock, the same lock git add and git commit need.

Editors, prompts and IDE integrations run git status constantly in the background. Each run can grab the lock at the wrong moment, and your real git commit fails with "Unable to create '.git/index.lock': File exists". GIT_OPTIONAL_LOCKS=0 tells Git to skip such optional writes; the output is the same, only the opportunistic refresh is dropped.

Terminal
GIT_OPTIONAL_LOCKS=0 git status
git --no-optional-locks status          # same thing as an option

Try it

Bash Status that refreshes the index versus status that does not

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Why a held lock hurts, and the option that avoids it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
GIT_OPTIONAL_LOCKS=0 git <command>
git --no-optional-locks <command>
Name Description
GIT_OPTIONAL_LOCKS If set to 0 (or false), Git does not take locks for opportunistic writes. Unset or any true value keeps the default behavior.
--no-optional-locks Command-line form; also exports the variable to child processes.

What is skipped: only writes that are an optimization, mainly refreshing the index after git status, git diff and similar. Writes that are the point of a command (git add, git commit, git checkout) are never skipped, and they still take their locks.

Edge cases: the output of status is identical either way. With the refresh skipped, a repository whose timestamps are out of date makes each status do more work, since Git must compare content again every time. That is a small cost for a few files and a noticeable one for a huge working tree.

Usage notes

  • Set it in background tools, not in your interactive shell: shell prompts, status bars, file watchers and editor plugins should use git --no-optional-locks status. Foreground commands benefit from the refresh.
  • The stale-lock message Unable to create '.git/index.lock': File exists means another Git is running or one crashed. Check for running processes before deleting the file.
  • Some tools already set it, and this site's runner has it enabled by default. The examples therefore use env -u to remove it for the default case.
  • Pair with a file-system monitor. With core.fsmonitor and the untracked cache, stat data matters less, and the refresh is cheaper.
  • It is inherited by commands Git starts, such as hooks, so a hook that runs git status does not fight the outer command either.