What does ‘adding to the index’ really mean in Git?

A useful metaphor

“Adding a file to the index”, “staging a file”, “adding a file to the staging area” are all synonymous.

I personally prefer the term staging area to index because it lends itself to a useful metaphor. If committing is akin to “taking a snapshot”, staging is about “composing the shot“.

Imagine yourself as a professional photographer about to take a a class picture: you gather all your subjects and get them ready for the photo, you make sure that they’re all there and that there are no intruders, that everything of importance is in the frame, etc. Then… Snap!

Of course, if you realise, right after taking the picture, that too many kids had their eyes closed (or that some kid was giving the teacher bunny ears!), you may want to scrap that first picture and take another, better one; in Git, that would correspond to amending the last commit. But I digress…

What happens when you add a (new) file to the index

To stage something, you would usually use the high-level (“porcelain”) git add command… or the exact equivalent git stage (introduced by Scott Chacon around Git v1.6) which I find much more intuitive, but doesn’t seem nearly as popular.

When you add a new file to the staging area, three things happen:

1. the file contents are hashed,
2. the file contents are stored in your repository’s database,
3. the file contents in your working tree are registered to the .git/index file.

Adding a file to the index with plumbing commands

As an experiment, to fix ideas, you can use low-level (“plumbing”) Git commands to reproduce what git add does in that simple case. Start from a brand new repository:

$ cd ~/Desktop
$ mkdir teststage
$ cd teststage
$ git init

Before doing anything else, go ahead and peer into the .git/objects folder.

$ ls -la .git/objects

You will see it only contains two (empty) subdirecties: info and pack. Create a file, say README.md:

$ printf "hello\n" > README.md

Now let’s stage README.md, one step at a time. First, use the lower-level git hash-object command to (1) hash the contents of README.md and (2) write the latter to the repository’s database.

$ git hash-object -w README.md
27728344ab3ae5b8aa334418d1e1b0f5be0ea0cc

(-w means write, here.)

Now, if you look into the .git/objects folder, you will see that the new object (a blob) has been added to the database:

$ tree -la .git/objects/
.git/objects
├── 27
│   └── 728344ab3ae5b8aa334418d1e1b0f5be0ea0cc
├── info
└── pack

There is one thing left to complete the staging of README.md. We need to (3) register the file contents to the index. Have a look inside .git, there should be no file called index in it, yet. Now, if you run

$ git update-index --add --info-only README.md

and then have another look inside .git, you’ll see that a binary index file has been created.

That’s it. You’ve staged README.md. It’s ready to go in your next commit. Check it for yourself:

$ git status
On branch master

Initial commit

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)

    new file:   README.md

Now you can make your first commit, if you want.