The 'fatal: unknown option --no-optional-locks' error occurs when a tool or script invokes Git with the --no-optional-locks flag, but the installed Git version is too old to support this option. This typically happens in CI/CD pipelines, IDEs, or build systems that expect a newer Git version.
The "--no-optional-locks" option was introduced in Git 2.15 (released October 2017). This flag tells Git to skip acquiring optional locks that could cause conflicts with concurrent processes or file system watchers. When you see "fatal: unknown option --no-optional-locks", it means the Git version installed on your system predates version 2.15 and doesn't recognize this flag. This error commonly appears in: - **CI/CD pipelines**: Build systems like GitHub Actions, GitLab CI, or Jenkins may use scripts or tools that pass this flag to Git - **IDE integrations**: Visual Studio Code, IntelliJ, and other editors use this flag to query Git status without interfering with concurrent Git operations - **Build tools**: Package managers, version control plugins, and automation scripts often rely on this flag for safer Git operations - **Docker containers**: Base images may include older Git versions that don't support newer flags The --no-optional-locks option is particularly useful when multiple processes access the same Git repository simultaneously, preventing lock file conflicts that could cause commands to fail or hang.
First, verify which Git version is installed:
# Check Git version
git --version
# Expected output for a version that supports --no-optional-locks:
# git version 2.15.0 or higherIf your version is below 2.15, you need to upgrade Git. You can also check when --no-optional-locks was added:
# Test if the flag is supported
git --no-optional-locks status
# If this fails with "unknown option", upgrade is neededThe default Git package in Ubuntu/Debian repositories is often outdated. Use the official Git PPA for the latest version:
# Add the official Git PPA
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt update
# Install or upgrade Git
sudo apt install git -y
# Verify the new version
git --versionFor Debian without add-apt-repository:
# Install dependencies
sudo apt install software-properties-common -y
# Add the PPA manually
echo "deb http://ppa.launchpad.net/git-core/ppa/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/git-core.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E1DD270288B4E6030699E45FA1715D88E1DF1F24
sudo apt update
sudo apt install git -yEnterprise Linux distributions often have older Git versions. Use the IUS repository or compile from source:
# For CentOS/RHEL 7+ - Use IUS repository
sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
sudo yum install -y git236 # or latest available
# For Amazon Linux 2
sudo yum install -y git
# For Amazon Linux 2023
sudo dnf install -y git
# For RHEL 8/9 or CentOS Stream
sudo dnf install -y gitIf repositories don't have a recent enough version, compile from source:
# Install build dependencies
sudo yum groupinstall -y "Development Tools"
sudo yum install -y curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-ExtUtils-MakeMaker
# Download and compile Git
cd /tmp
curl -LO https://github.com/git/git/archive/refs/tags/v2.43.0.tar.gz
tar -xzf v2.43.0.tar.gz
cd git-2.43.0
make prefix=/usr/local all
sudo make prefix=/usr/local install
# Verify installation
/usr/local/bin/git --versionmacOS includes Git with Xcode Command Line Tools, but it may be outdated:
# Update Xcode Command Line Tools (includes Git)
xcode-select --install
# Or install/update via Homebrew (recommended)
brew install git
# Ensure Homebrew's Git takes priority
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Verify
which git # Should show /opt/homebrew/bin/git
git --versionIf using an Intel Mac:
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcUpdate Git for Windows to the latest version:
# If Git is already installed, update it
git update-git-for-windows
# Or download the latest installer from:
# https://git-scm.com/download/winUsing Chocolatey:
choco upgrade git -yUsing winget:
winget upgrade Git.GitAfter updating, restart your terminal or IDE to pick up the new version.
Update your Dockerfile to install a recent Git version:
Alpine Linux:
FROM alpine:3.19
# Alpine 3.15+ includes Git 2.34+
RUN apk add --no-cache gitUbuntu/Debian:
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y software-properties-common \
&& add-apt-repository ppa:git-core/ppa -y \
&& apt-get update \
&& apt-get install -y git \
&& rm -rf /var/lib/apt/lists/*Amazon Linux 2:
FROM amazonlinux:2
RUN yum install -y tar gzip make gcc curl-devel expat-devel gettext-devel \
openssl-devel zlib-devel perl-ExtUtils-MakeMaker && \
cd /tmp && \
curl -LO https://github.com/git/git/archive/refs/tags/v2.43.0.tar.gz && \
tar -xzf v2.43.0.tar.gz && \
cd git-2.43.0 && \
make prefix=/usr all && \
make prefix=/usr install && \
rm -rf /tmp/git-* && \
yum clean allUpdate your CI/CD configuration to use a recent Git version:
GitHub Actions:
jobs:
build:
runs-on: ubuntu-latest
steps:
# GitHub-hosted runners have recent Git, but you can update if needed:
- name: Update Git
run: |
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt-get update
sudo apt-get install -y git
git --version
- uses: actions/checkout@v4GitLab CI:
default:
image: ubuntu:22.04
before_script:
- apt-get update && apt-get install -y software-properties-common
- add-apt-repository ppa:git-core/ppa -y
- apt-get update && apt-get install -y git
- git --versionJenkins:
pipeline {
agent any
stages {
stage('Setup') {
steps {
sh '''
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt-get update
sudo apt-get install -y git
git --version
'''
}
}
}
}If you cannot upgrade Git, you can work around the issue by modifying how Git is called:
Wrapper script approach:
#!/bin/bash
# Save as /usr/local/bin/git-wrapper and make it executable
# This strips --no-optional-locks from arguments
args=()
for arg in "$@"; do
if [[ "$arg" != "--no-optional-locks" ]]; then
args+=("$arg")
fi
done
/usr/bin/git "${args[@]}"VS Code setting:
Add to your VS Code settings.json to use a different Git path or disable features requiring the flag:
{
"git.path": "/path/to/newer/git",
"git.useOptionalLocks": false
}Note: VS Code's git.useOptionalLocks setting (if available in your version) controls whether --no-optional-locks is used.
Environment variable workaround:
Some tools check for Git version before using --no-optional-locks:
# Fake Git version for tools that check (not recommended for production)
export GIT_VERSION_OVERRIDE="2.30.0"If you have multiple Git installations, ensure the correct one is used:
# Find all Git installations
which -a git
type -a git
# Check PATH order
echo $PATH | tr ':' '\n' | head -20
# Common locations for Git:
# /usr/local/bin/git (compiled from source)
# /usr/bin/git (system package)
# /opt/homebrew/bin/git (Homebrew on Apple Silicon)
# /usr/local/bin/git (Homebrew on Intel Mac)Ensure the newer Git appears first in PATH:
# Add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"
# Apply changes
source ~/.bashrcFor system-wide configuration:
# Create symlink to override system git
sudo ln -sf /usr/local/bin/git /usr/bin/git### About the --no-optional-locks Flag
The --no-optional-locks option was added in Git 2.15 to support better integration with file system watchers and IDE tools. Here's what it does:
# Normal Git status acquires a lock
git status
# With --no-optional-locks, Git skips non-essential locks
git --no-optional-locks statusWhy this flag exists:
1. File system watchers: IDEs like VS Code constantly poll Git status. Without this flag, each poll could block other Git operations
2. Network file systems: Lock files on NFS or SMB mounts can cause issues
3. Concurrent operations: CI/CD systems may run multiple Git commands simultaneously
### Git Version History Reference
| Git Version | Release Date | Notable Features |
|------------|--------------|------------------|
| 2.15 | Oct 2017 | --no-optional-locks added |
| 2.17 | Apr 2018 | Improved submodule support |
| 2.20 | Dec 2018 | Protocol v2 improvements |
| 2.22 | Jun 2019 | Partial clone support |
| 2.25 | Jan 2020 | Sparse checkout redesign |
| 2.30 | Dec 2020 | SHA-256 support |
| 2.38 | Oct 2022 | Scalar integrated |
| 2.43 | Nov 2023 | Performance improvements |
### Common OS Git Versions
| Operating System | Default Git Version | Notes |
|-----------------|---------------------|-------|
| Ubuntu 20.04 | 2.25.1 | Supports --no-optional-locks |
| Ubuntu 22.04 | 2.34.1 | Supports --no-optional-locks |
| Ubuntu 18.04 | 2.17.1 | Supports --no-optional-locks |
| CentOS 7 | 1.8.3 | Does NOT support --no-optional-locks |
| Amazon Linux 2 | 2.40+ | Supports --no-optional-locks |
| Alpine 3.14 | 2.32 | Supports --no-optional-locks |
| Debian 10 | 2.20.1 | Supports --no-optional-locks |
| macOS Monterey | 2.32+ | Supports --no-optional-locks |
### Checking Tool-Specific Configuration
VS Code:
VS Code uses --no-optional-locks by default when querying Git. Check the Git output channel for errors:
1. Open Command Palette (Ctrl+Shift+P)
2. Type "Git: Show Git Output"
3. Look for "unknown option" errors
npm/yarn:
Some Node.js tools use Git for version detection:
# Check if npm is calling Git
npm config set loglevel verbose
npm install 2>&1 | grep -i gitPre-commit hooks:
Check your .pre-commit-config.yaml or .husky configuration:
# See what's calling Git in hooks
cat .git/hooks/pre-commit### Building Git from Source (All Platforms)
For maximum control over Git version:
# Download source
git clone https://github.com/git/git.git --depth 1 --branch v2.43.0
cd git
# Build with all features
make prefix=/usr/local all doc info
sudo make prefix=/usr/local install install-doc install-html install-info
# Verify
hash -r # Clear command hash table
git --version### Container Security Note
When building containers, prefer using official images with recent Git:
# Good: Use specific, recent base image
FROM node:20-bookworm
# Better: Use multi-stage build to minimize surface
FROM node:20-alpine AS builder
RUN apk add --no-cache git
# ... build steps ...
FROM node:20-alpine
COPY --from=builder /app /appwarning: 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