Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

Index file format

Reference for the .git/index file: the DIRC header, cache entries with stat data and flags, stage numbers during conflicts, and extensions such as TREE and UNTR.

The index, also called the staging area or cache, is the binary file .git/index. It is a sorted list of every path Git tracks, each with the mode and blob ID that the next commit would contain, plus cached file-system data that lets Git notice changes without reading every file. git add updates it, git commit turns it into a tree, and git status compares it with both HEAD and the working directory.

During a merge conflict the same path can appear up to three times, in different stages. That is how Git remembers the common ancestor and both sides until you resolve the conflict.

Terminal
git ls-files --stage      # path, mode, blob ID and stage number
git ls-files --debug      # also the cached stat data
git update-index --add --cacheinfo 100644,<blob>,<path>

Try it

Bash Entries and stage numbers during a conflict

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Edit the index without touching the working directory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Format

The file begins with a 12-byte header, followed by the entries and optional extensions, and ends with a checksum of everything before it.

Header field Description
Signature The four bytes DIRC ("dircache").
Version Four bytes, big-endian: 2, 3 or 4.
Entry count Four bytes, big-endian.

Entries

Entries are sorted by path name (bytes), then by stage. Each entry stores:

Field Description
ctime, mtime Seconds and nanoseconds of the last status and data changes, used to guess whether the file changed.
dev, ino Device and inode numbers (zero on systems without them).
mode Object type and permission bits: 100644, 100755, 120000 or 160000.
uid, gid Owner and group.
size File size in bytes, truncated to 32 bits.
object ID The blob ID (20 or 32 bytes).
flags Two bytes: assume-valid bit, extended-flags bit, a 2-bit stage number and a 12-bit name length (0xFFF means longer).
extended flags Version 3 and 4 only: skip-worktree and intent-to-add bits.
path NUL-terminated name; versions 2 and 3 pad the entry to a multiple of 8 bytes, version 4 compresses names by sharing a prefix with the previous entry.

The stage in the flags is 0 for a normal entry. During a conflict, stage 1 is the common ancestor, stage 2 is the current branch ("ours") and stage 3 is the branch being merged ("theirs"). Resolving a path with git add replaces the three entries with one stage-0 entry.

Extensions

Extensions start with a four-byte signature. Uppercase first letter means Git can ignore it if unknown.

Signature Purpose
TREE Cached tree objects for directories, so git commit and write-tree can reuse unchanged sub-trees.
REUC "Resolve undo" data, remembered so git checkout -m can recreate a conflict.
UNTR Untracked cache, which speeds up git status.
FSMN File-system monitor data (see core.fsmonitor).
EOIE, IEOT End-of-index and offset tables, which allow loading entries on several threads.
link Split index: the main part lives in sharedindex.<hash>.
sdir Sparse directory entries for sparse-index mode.

Usage notes

  • Never edit it by hand. Use git add, git rm, git reset, git update-index. The checksum and sorting must stay valid.
  • Racy timestamps. If a file is modified in the same instant the index is written, Git cannot trust the cached stat data and re-reads the content once. This is invisible to you except for a slightly slower first status.
  • .git/index.lock. Every write goes through this lock file. A leftover one after a crash makes the next write fail with "Unable to create index.lock"; delete it only when no Git process is running.
  • Per-worktree. Each linked worktree has its own index. GIT_INDEX_FILE points a command at another index (see GIT_INDEX_FILE).
  • Intent to add. git add -N records an empty placeholder so a new file appears in git diff before it is staged.
  • Skip-worktree and assume-unchanged are index flags with different goals: sparse checkout and a performance hint. See update-index flags.
  • Index version. index.version selects the format for new indexes; feature.manyFiles enables version 4.