What "git add" Really Means


Posted by giles at November 5th, 2008

Not being a git expert, I still sometimes stumble on straightforward things. Recently I did a git checkout and ran into merge difficulties. One version of a spec had a particular example commented out; another version didn't. I wrestled git for a while, trying to find a way to tell it, "Dude I don't care, pick one file or the other so I can get on with my day." Neither version of the file mattered, because after a day or two more of work, the branch won't need the file at all.

After searching for a simpler solution, I cleaned the file up by hand, did git add filename, plus git commit filename, and I was done. Some of the messages I got during the process were confusing, however, and I didn't remember right away that you're supposed to git add a file that git already knows about.

The first time you use git, people tell you, first you git add the new files git needs to know about, and then you git commit those files. It's pretty easy to leap to the conclusion that git add means "add this file to the list of things git cares about," which makes this use case a little counter-intuitive, or at least less obvious than I would have liked. It's kind of like git has Alzheimer's and you have to introduce it to the same new person twice.

A git tutorial on the GNU Smalltalk blog has part of the answer:

What git add does is to move the current version of the named file to a special staging area, holding files that are ready to be committed

The GitHub blog reports that git add may soon take on the new name git stage, to reflect this.

I’m excited that staging files may soon be done via ‘git stage’ rather-than/in-addition-to ‘git add’. This is nice for new users who often have a hard time seeing why you have to keep ‘git add’ing to stage your changes.

The GNU Smalltalk git tutorial's interesting and worth reading. I also stumbled across an awesome feature I hadn't known about: git add (aka stage) has an interactive console like IRB or the Rails console. You can also use it for commits. I'm going to give that a whirl and I'll post here if I get any interesting results.


  1. Mark Mark said on November 5th, 2008

    I’ve found it helpful to think of git-add as meaning “git add new content from the following files” as opposed to “git add these files”.

  2. Giles Bowkett Giles Bowkett said on November 7th, 2008

    That makes sense. If you realize the index is a staging area, adding things to it is easy enough.

    I just went ahead and created a git alias to match the upcoming name change. Now I just type “git stage” instead of “git add.”

  3. Paul Paul said on November 29th, 2008

    This is one of the places where Git semantics lead you to think that Git is working with files (like every other VCS I’ve used), when actually it works with file contents.

    Great idea to alias ‘git add’ as ‘git stage’.

Make your voice heard

Sorry, but comments are closed for this item.