Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Concepts

The staging area (index)

Understand the Git staging area: what the index holds, why commits are built from it, how partial staging works and how to inspect it.

The staging area, also called the index, is the place where Git assembles your next commit. When you run git commit, Git does not look at your working directory. It takes a snapshot of whatever is in the index and turns that into a commit. Running git add copies the current content of a file into the index.

This extra step looks like bureaucracy at first, but it gives you control. You can edit ten files and commit only three of them, or even commit half of the changes in one file. The result is a history made of small, focused commits instead of "everything I did today".

Terminal
git add file.txt          # copy file.txt as it is now into the index
git add -p                # choose individual hunks
git diff                  # working tree vs index (unstaged changes)
git diff --staged         # index vs HEAD (what the next commit will contain)
git ls-files --stage      # list the index itself

Try it

Bash Working tree, index and HEAD differ

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 Looking inside the index

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.

How it works

The index is a binary file, .git/index. It lists every tracked path with its file mode, the id of the stored blob and some cached file system data (size, modification time) that makes git status fast. Because git add writes the content into the object database right away, the staged version is safe even if you later change or delete the file on disk.

A commit is built in two steps: git write-tree turns the index into tree objects, and git commit-tree wraps that tree in a commit. git commit does both for you.

During a merge conflict the index also holds up to three versions of each conflicted file (stages 1, 2 and 3: base, ours, theirs). git ls-files --stage shows them; staging the resolved file collapses them back into stage 0.

Usage notes

  • git add takes a snapshot. If you edit a file after staging it, the new edit is not part of the next commit until you stage the file again. git status shows such a file twice, once as staged and once as modified.
  • Skip the index when you want to. git commit -a stages every modified tracked file first (it does not add new files). git commit file.txt commits only the named paths, ignoring the rest of the index.
  • Partial staging. git add -p splits changes into hunks, and git add -e lets you edit a patch by hand. See git add.
  • Unstage without losing work. git restore --staged file copies HEAD's version back into the index and leaves the working file alone.
  • git diff versus git diff --staged. The first compares working tree and index, the second compares index and HEAD. Confusing the two is the most common reason people think "my diff is empty".
  • The index is also a cache. Racy timestamps are rechecked by content, so touching a file does not make it "changed" if the bytes are identical.
  • Deleting .git/index is recoverable with git reset, which rebuilds it from HEAD, but staged-only changes that were never committed are lost as index entries (the blobs may still be found with git fsck --lost-found).