The Staging Area

There's something I need to tell you.

You should probably sit down for this.

I lied to you, back when I was explaining how to commit things.

I implied, back then, that Git keeps a list somewhere of the files you want it to manage. I told you that the "git add" command would add files to this list. After that, I instructed you to run "git commit -a" to commit things, without any further discussion of the -a switch or what it means.

The fact is, Git keeps no such list of files, "git add" doesn't really add them to this fictional list, and the -a switch is the only reason you could get along using Git without knowing the truth.

You see, Git has this odd little thing called the "index", or "staging area". You might think of it as a space that exists between the files you work with directly (your working tree) and the things you have committed (the repository).

Most of the time, the index is a pristine copy of whatever revision you are working with, lacking any of the changes that exist in your working tree. From time to time, you may "stage" your changes in the index using the "git add" command. If you use it without any switches, the "git commit" command will create a commit using what is in the index and completely ignoring what's in your working tree.

The "orthodox" way to make a commit goes something like this:

  1. Hack away on your local tree until you decide you want to make a commit.
  2. Carefully decide which changes you want to appear in your commit, and add them to the index.
  3. Carefully inspect the contents of the index, to make sure everything is as it should be.
  4. Run "git commit" and enter your commit message.

Personally, I almost never do it that way, but on the occasions when I do take advantage of the index, I'm glad its there.

I'm not glad it's there when I have to explain to someone who is completely new to Git, possibly new to version control in general, that there is this creepy other thing they have to deal with before they can make commits.

I did not have time for that.

As you'll recall, your data was in danger. Every minute that passed was important. Taking time out to explain this extra thing would have been irresponsible.

So I did what I usually do when I want the index to go away: I used the -a switch. The -a switch modifies git commit so that, before committing, it copies any changes from the working tree into the index, as long as the files changed are already in the index.

No one would ever have to know it's there.

Except for one thing: you have to get your files into the index first or even "git commit -a" will ignore them. So I invented a "tracked files" list and made the claim that "git add" added files to that list.

Vincent Povirk