This error occurs when your CI environment's Git version is too old to support the sparse-checkout command. The git sparse-checkout subcommand requires Git 2.25 or newer. Upgrade Git in your CI environment or use the legacy sparse-checkout configuration method.
This error message appears when a CI/CD pipeline attempts to use the `git sparse-checkout` command, but the Git version installed in the CI environment doesn't support it. The `git sparse-checkout` subcommand was introduced in **Git 2.25.0** (January 2020), so any environment running an older Git version will fail with this error. The error commonly manifests in several forms: - `git: 'sparse-checkout' is not a git command. See 'git --help'` - `error: sparse-checkout is not supported in this CI environment` - `Error: The process '/usr/bin/git' failed with exit code 1` This is particularly common when using Docker containers with older base images (like `python:2.7.18-buster`) or CI runners that haven't been updated recently. The error can also occur when CI tools like GitHub Actions' `actions/checkout@v4` attempt to use sparse-checkout features unconditionally, without first checking Git version compatibility. While sparse-checkout functionality existed in Git prior to version 2.25 via the `core.sparseCheckout` config option, the convenient `git sparse-checkout` command is only available in newer versions.
First, identify what Git version is available in your CI environment:
# GitHub Actions
- name: Check Git version
run: git --version
# GitLab CI
check_git:
script:
- git --version
# Jenkins (Groovy)
sh 'git --version'
# Azure DevOps
- script: git --versionThe output will show something like git version 2.20.1. If the version is below 2.25.0, the git sparse-checkout command won't be available.
Version requirements:
- Git 2.25.0+: Basic sparse-checkout command
- Git 2.27.0+: Cone mode improvements
- Git 2.28.0+: Full partial clone and sparse-checkout integration
The most reliable fix is upgrading Git to version 2.25 or newer.
GitHub Actions (Ubuntu runners):
- name: Install latest Git
run: |
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt-get update
sudo apt-get install git -y
git --versionDocker container (Debian/Ubuntu):
# Add git-core PPA and install latest Git
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/*Docker container (Alpine):
# Alpine usually has recent Git versions
RUN apk add --no-cache gitGitLab CI:
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 --versionIf you cannot upgrade Git, use the legacy sparse-checkout configuration that works with Git 1.7.0+:
# Enable sparse checkout via config
git config core.sparseCheckout true
# Create sparse-checkout patterns file
mkdir -p .git/info
echo 'path/to/directory/' >> .git/info/sparse-checkout
echo 'another/path/' >> .git/info/sparse-checkout
# Apply the sparse checkout
git read-tree -mu HEADCI pipeline example (GitHub Actions):
- name: Checkout with legacy sparse-checkout
run: |
git clone --no-checkout --depth 1 ${{ github.server_url }}/${{ github.repository }}.git .
git config core.sparseCheckout true
echo 'src/' >> .git/info/sparse-checkout
echo 'package.json' >> .git/info/sparse-checkout
git checkout ${{ github.sha }}Pattern syntax for older Git versions:
- dir/ - Include entire directory tree
- dir/* - Include only files directly in dir (not subdirectories)
- !path/ - Exclude a path
If the error comes from a CI tool (like actions/checkout) trying to use sparse-checkout features unconditionally, pin to an older version:
GitHub Actions - Use checkout v3:
# v4 may fail on old Git; v3 is more compatible
- uses: actions/checkout@v3Or disable sparse-checkout in v4:
- uses: actions/checkout@v4
with:
sparse-checkout: "" # Explicitly disable sparse-checkoutThe issue occurs because actions/[email protected] calls git sparse-checkout disable even when sparse-checkout wasn't enabled, which fails on Git versions that don't have the command.
Jenkins Git Plugin:
The Jenkins Git plugin has supported sparse checkouts since version 2.1.0 (2014), but uses its own implementation. Check your plugin version:
checkout([
$class: 'GitSCM',
extensions: [[$class: 'SparseCheckoutPaths',
sparseCheckoutPaths: [[path: 'src/']]]]
])If using Docker in CI, switch to a base image with a newer Git version:
Update Debian/Ubuntu base:
# Instead of older images
# FROM python:2.7.18-buster # Has old Git
# Use newer base images
FROM python:3.11-bookworm # Debian 12, Git 2.39+
FROM ubuntu:22.04 # Git 2.34+
FROM ubuntu:24.04 # Git 2.43+Check Git version in common base images:
| Base Image | Git Version |
|------------|-------------|
| ubuntu:18.04 | 2.17.1 (too old) |
| ubuntu:20.04 | 2.25.1 (minimum) |
| ubuntu:22.04 | 2.34.1 |
| debian:buster | 2.20.1 (too old) |
| debian:bullseye | 2.30.2 |
| debian:bookworm | 2.39.2 |
| alpine:3.18 | 2.40.1 |
Multi-stage build to add Git:
FROM python:3.9-slim AS base
# Install newer Git
RUN apt-get update && \
apt-get install -y --no-install-recommends \
software-properties-common && \
add-apt-repository ppa:git-core/ppa -y && \
apt-get update && \
apt-get install -y --no-install-recommends git && \
rm -rf /var/lib/apt/lists/*For Git versions between 2.25 and 2.28, you may need additional configuration for partial clone features:
# Required for --filter option with git fetch in older versions
git config extensions.partialClone origin
# Then you can use partial clone with sparse-checkout
git clone --filter=blob:none --no-checkout <url>
git sparse-checkout init --cone
git sparse-checkout set path/to/dir
git checkout mainGitHub Actions with partial clone:
- uses: actions/checkout@v4
with:
sparse-checkout: |
src
package.json
sparse-checkout-cone-mode: true
filter: blob:noneNote: The --filter=blob:none option downloads commits and trees but not file contents until needed, significantly reducing clone time for large repos.
If upgrading Git isn't possible and legacy sparse-checkout is too complex, consider these alternatives:
Shallow clone with specific paths (Git 2.19+):
# Clone only recent history
git clone --depth 1 <repository-url>
# Remove unwanted directories after clone
rm -rf unwanted-dir/Use git archive for specific paths:
# Download specific directory as archive (works with remote repos)
git archive --remote=<repository-url> HEAD:path/to/dir | tar -xGitLab CI with GIT_STRATEGY:
variables:
GIT_STRATEGY: none
job:
script:
- git init
- git remote add origin $CI_REPOSITORY_URL
- git config core.sparseCheckout true
- echo "src/" >> .git/info/sparse-checkout
- git fetch --depth 1 origin $CI_COMMIT_SHA
- git checkout FETCH_HEADAzure DevOps manual checkout:
- checkout: none
- script: |
git init
git remote add origin $(Build.Repository.Uri)
git config core.sparseCheckout true
echo "src/" >> .git/info/sparse-checkout
git fetch --depth 1 origin $(Build.SourceVersion)
git checkout FETCH_HEAD### Git Sparse-Checkout Version History
| Git Version | Feature |
|-------------|---------|
| 1.7.0 | Basic sparse checkout via core.sparseCheckout config |
| 2.25.0 | git sparse-checkout command introduced |
| 2.26.0 | Cone mode added for better performance |
| 2.27.0 | Improved behavior with --no-checkout clones |
| 2.28.0 | extensions.partialClone no longer required for --filter |
| 2.32.0 | Sparse index support for faster operations |
### CI Platform-Specific Notes
GitHub Actions:
- Ubuntu 20.04 runners have Git 2.25.1 (minimum supported)
- Ubuntu 22.04 runners have Git 2.34.1
- actions/checkout@v4 may unconditionally try to disable sparse-checkout
- Use sparse-checkout: "" to disable the feature explicitly
GitLab CI:
- Default runners use the Git version from the Docker image
- Set GIT_STRATEGY: none to manually control checkout
- GitLab 14.0+ supports sparse checkout in CI/CD settings
Jenkins:
- Git plugin handles sparse checkout internally since version 2.1.0
- Configure via "Additional Behaviors" > "Sparse Checkout paths"
- Plugin version matters more than Git version for built-in support
Azure DevOps:
- Pipeline agents have Git 2.30+ on recent images
- Use checkout: none and script-based checkout for fine control
- Sparse checkout support varies by agent pool
### Debugging CI Git Issues
# Full Git environment info
git --version
git config --list --show-origin
# Check if sparse-checkout command exists
git sparse-checkout 2>&1 | head -5
# Verify extensions support
git config --get extensions.partialClone
# List available Git commands
git --list-cmds=main,others | grep sparse### Performance Considerations
Sparse checkout reduces working directory size but not repository size. For true bandwidth savings in CI:
1. Partial clone (--filter=blob:none): Skip downloading file contents
2. Shallow clone (--depth=1): Skip history
3. Sparse checkout: Skip files in working directory
Combine all three for maximum CI speedup:
git clone --filter=blob:none --depth=1 --sparse <url>
git sparse-checkout set path/to/needed/files### Common CI Workflow Patterns
Monorepo with path-based triggers:
# GitHub Actions
on:
push:
paths:
- 'packages/my-app/**'
jobs:
build:
steps:
- uses: actions/checkout@v4
with:
sparse-checkout: |
packages/my-app
packages/shared
sparse-checkout-cone-mode: trueFallback pattern for version compatibility:
- name: Checkout (try modern, fallback to legacy)
run: |
git clone --no-checkout $REPO_URL .
if git sparse-checkout init --cone 2>/dev/null; then
git sparse-checkout set src/ package.json
else
git config core.sparseCheckout true
echo 'src/' >> .git/info/sparse-checkout
echo 'package.json' >> .git/info/sparse-checkout
fi
git checkout HEADkex_exchange_identification: Connection closed by remote host
Connection closed by remote host when connecting to Git server
fatal: unable to access: Proxy auto-configuration failed
How to fix 'Proxy auto-configuration failed' in Git
fatal: unable to access: Authentication failed (proxy requires basic auth)
How to fix 'Authentication failed (proxy requires basic auth)' in Git
fatal: unable to access: no_proxy configuration not working
How to fix 'no_proxy configuration not working' in Git
fatal: unable to read tree object in treeless clone
How to fix 'unable to read tree object in treeless clone' in Git