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".
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
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.
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 addtakes 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 statusshows such a file twice, once as staged and once as modified.- Skip the index when you want to.
git commit -astages every modified tracked file first (it does not add new files).git commit file.txtcommits only the named paths, ignoring the rest of the index. - Partial staging.
git add -psplits changes into hunks, andgit add -elets you edit a patch by hand. See git add. - Unstage without losing work.
git restore --staged filecopies HEAD's version back into the index and leaves the working file alone. git diffversusgit 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/indexis recoverable withgit 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 withgit fsck --lost-found).