git-checkout-index

Restore any files deleted since the last commit

$ git checkout-index [[-a|--all]]

$ git checkout-index [[-a|--all]] [[-f|--force]]

$ git checkout-index [[-a|--all]] [[-f|--force]] [[-n|--no-create]]

$ git checkout-index [[-a|--all]] [[-f|--force]] --prefix [path/to/export_directory]/

git checkout-index [options] [--] [file...]
git checkout-index --stdin [options]

-u, --unmerged
    Do not abort on unmerged entries. Instead, extract stage #2 (the 'theirs' side) for conflicted paths.

-a, --all
    Checkout all files in the index. Cannot be used with explicit file paths.

-f, --force
    Overwrite existing files in the working tree without prompting.

-n, --no-create
    Do not create new files. Only update existing files that match the index content.

-q, --quiet
    Suppress error messages for files that already exist and would be overwritten without --force.

-z, --null
    Input/output paths are NUL-terminated. Useful when combined with commands like git ls-files -z.

--prefix=
    When checking out, write files to the specified path prefix instead of the current working directory.

--stage=
    When checking out unmerged entries, select a specific stage number (1, 2, or 3) to extract. Cannot be used with --unmerged. Stage 1 is the base, 2 is 'theirs', and 3 is 'ours'.

--sparse
    Respect the sparse-checkout definition when checking out files. Only relevant if sparse-checkout is enabled for the repository.

--index-info
    Read index information from standard input, using the format specified by git update-index --index-info. Primarily for internal or advanced scripting use.

--stdin
    Read file paths from standard input, one per line (or NUL-terminated with -z), instead of from command-line arguments.

--
    Separates options from the list of explicit file paths, allowing filenames that start with a hyphen to be specified.

...
    Optional list of specific files to checkout from the index. If omitted and --stdin is not used, all files are checked out (requires -a).

git checkout-index is a Git plumbing command used to copy files from the Git index (also known as the staging area) to the working tree. Unlike the higher-level git checkout command, git checkout-index does not update HEAD or switch branches. It's primarily designed for scripting and low-level repository manipulation, allowing precise control over which files are extracted and where they are placed.

It can be used to restore specific files from the index, inspect the content of the staging area, or prepare files for external tools. It can overwrite existing files if forced, and has options to handle unmerged entries in the index. This command provides a direct interface to the contents of the index, making it powerful for custom Git workflows but less commonly used for routine operations.

git checkout-index is a plumbing command, meaning it's a lower-level building block of Git and is not typically used by end-users directly for day-to-day operations. It does not update your HEAD or move your branch pointer. It can overwrite existing files in your working directory, potentially leading to data loss if not used carefully, especially with the --force option. It also does not manage .git/info/sparse-checkout directly; it respects it if --sparse is used.

While git checkout-index can retrieve files from the index, it's important to understand its limitations. It does not perform merge operations, handle conflicts gracefully (unless specific stages are requested for unmerged paths), or update any Git references. It is best suited for scenarios like:

• Restoring specific files from the staging area that might have been accidentally deleted from the working tree.
• Extracting files from the index into a temporary location for inspection or processing by external tools.
• Building custom Git workflows or scripts that require precise control over the working directory content based on the index.

When the index contains unmerged entries (due to a conflict), git checkout-index normally aborts if it encounters such a path. The --unmerged option forces it to extract stage #2 (the version from 'theirs'). The --stage=<number> option provides more granular control, allowing extraction of stage #1 (base), #2 (theirs), or #3 (ours) for conflicted paths. This is particularly useful in scripting custom merge resolution tools or inspecting conflict states.

git-checkout-index has been a core part of Git since its early days, serving as a fundamental tool for manipulating the index and working tree at a low level. It predates many of the user-friendly porcelain commands and remains crucial for Git's internal operations and for advanced scripting scenarios where direct control over the index is required. Its interface has remained relatively stable, reflecting its foundational role in Git's architecture.

git checkout(1), git read-tree(1), git update-index(1), git ls-files(1), git restore(1)