git checkout-index

The plumbing that 'switch' uses to write files.

🎯 What & why

git checkout-index is the plumbing command that copies blob contents from the index out to files on disk. It is what high-level git checkout/git switch/git restore actually call to materialize the working tree.

🧠 Mental model

Reads index entries (paths + blob OIDs + mode) and writes the matching blob content from the object DB to the filesystem. It does not touch refs, HEAD, or the index itself; it only produces files. With --prefix it can spray those files into any directory you like.

🛠️ Synopsis

git checkout-index [-u|--index] [-q|--quiet] [-f|--force] [-a|--all]
                   [-n|--no-create] [--prefix=<string>]
                   [--stage=<number>|all] [--temp]
                   [-z] [--stdin] [--] [<file>...]

🎚️ Switches & options

Flag	What it does
`-u, --index`	Also update the index's stat info to match the freshly-written file (so `git status` stays clean).
`-q, --quiet`	Suppress warnings about files that already exist or other non-fatal noise.
`-f, --force`	⚠️ Overwrite existing files in the working tree — silently clobbers local edits.
`-a, --all`	Check out every entry in the index, not just the listed paths.
`-n, --no-create`	Update existing files only; do NOT create files that don't yet exist.
`--prefix=<string>`	Prepend <string> to each output path. Trailing `/` makes it a directory; otherwise it's a literal filename prefix.
`-z`	NUL-terminate input/output paths (pairs with `--stdin` for filenames containing newlines).
`--stdin`	Read the list of paths from stdin instead of the command line.

💡 Use cases

Export a clean copy of the index to another directory: git checkout-index -a --prefix=/tmp/out/.
Restore a single file from the index without disturbing siblings or HEAD.
Scripted release builds that need the staged tree dropped into a build directory.
Recreate a deleted file that still exists in the index without using git restore.

🧪 Examples

Dump entire index to a build dir

git checkout-index -a -f --prefix=/tmp/build/

Restore one file from index

git checkout-index -f -- path/to/file

Update index stat after writing

git checkout-index -u -a

Read paths from stdin (NUL-terminated)

git ls-files -z | git checkout-index -z --stdin -f

🎓 Recommendations

Use --prefix=dir/ (with trailing slash) when exporting — without it you get filename prefixing, which is almost never what you want.
Pair -a -f with -u when scripting a clean checkout, so the index's stat cache stays in sync with the new files.
For day-to-day file restoration, prefer git restore --source=... — checkout-index is for plumbing and scripts.

🪤 Common pitfalls

-f will happily destroy local modifications without prompting — there is no safety net.
Forgetting the trailing / on --prefix turns it into a per-filename prefix string, scattering oddly-named files into the cwd.
It writes from the INDEX, not from HEAD — if the index is dirty/staged, you get those staged contents, not the committed tree.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.