Git Basics: Limit Working Files with Sparse Checkout

A repository can contain more directories than one task needs. Sparse checkout controls which tracked paths appear in the working tree. This local fixture selects one application, then restores the complete tree.

Prepare a scratch directory

Tested on Linux with Git 2.52.0 and GNU Bash 5.2.37. You need the named runtime, Bash, a text editor, and the standard mktemp, rm, and rmdir utilities. The script creates a second temporary fixture directory and removes only that directory through its exit trap. Run it in a normal Bash terminal, outside any Git hook or Git wrapper. No global Git configuration is changed.

Keep using the same terminal. Stop if setup fails, before saving the source:

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as demonstrate-sparse-checkout.sh:

#!/usr/bin/env bash
set -euo pipefail
export LC_ALL=C
fixture_dir="$(mktemp -d)"
trap 'rm -rf -- "$fixture_dir"' EXIT
export GIT_CONFIG_NOSYSTEM=1
export GIT_CONFIG_GLOBAL=/dev/null
unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE
git init -q -b main "$fixture_dir/repo"
cd -- "$fixture_dir/repo"
git config user.name 'Practice Author'
git config user.email 'practice@example.invalid'
mkdir -p apps/web apps/worker docs
printf 'root\n' > README.txt
printf 'web\n' > apps/web/index.txt
printf 'worker\n' > apps/worker/job.txt
printf 'guide\n' > docs/guide.txt
git add .
git commit -qm 'Project layout'
git sparse-checkout set --cone apps/web
test -f README.txt
test -f apps/web/index.txt
test ! -e apps/worker/job.txt
test ! -e docs/guide.txt
printf 'Selected directory: %s\n' "$(git sparse-checkout list)"
printf 'Tracked worker content still in HEAD: '
git show HEAD:apps/worker/job.txt
git sparse-checkout disable
test -f apps/worker/job.txt
test -f docs/guide.txt
test -z "$(git status --porcelain)"
printf 'Complete clean working tree restored\n'

Run it:

bash demonstrate-sparse-checkout.sh

Observed output:

Selected directory: apps/web
Tracked worker content still in HEAD: worker
Complete clean working tree restored

Read the result

Cone mode selects directory boundaries. Files directly in the repository root remain available, which is why README.txt survives. The worker file disappears from the working tree but remains in the committed tree: git show can still read it. Disabling sparse checkout repopulates the tracked paths, and the final assertion confirms the operation did not change committed content.

Apply it carefully

Sparse checkout is not a confidentiality boundary and does not remove objects from the repository. It is also distinct from partial clone, which controls object transfer. Start with a clean working tree and inspect warnings about local changes; do not delete files merely because they fall outside a new selection. These commands use modern Git cone-mode behavior and were tested with the version below.

The official reference describes the API and its options. The checks above cover the specific fixture, not every possible input or environment.

Clean up

Remove the source and then the empty practice directory:

rm -- demonstrate-sparse-checkout.sh
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

If the directory is not empty, inspect the remaining files rather than deleting unknown contents.

Acknowledgements

This post was created with assistance from AI.