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.
GIT_OPTIONAL_LOCKS=0 git status git --no-optional-locks status # same thing as an option
Try 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.
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
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 existsmeans 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 -uto remove it for the default case. - Pair with a file-system monitor. With
core.fsmonitorand 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 statusdoes not fight the outer command either.