The git add command for beginners

What does the git add command do?

Developers use the git add command to select the files to be included in the next git commit.

Git does not include every updated or edited file in a project in a commit. Git only includes files explicitly added to its staging index through the git add command. This is why issuing the git add command is often referred to as ‘staging a file’ or ‘adding a file to the index.’

Git’s primary purpose is to act as a version control tool. This means Git can track the changes to files and folders in your software project over time.

However, Git doesn’t behave like Microsoft Word’s autosave feature. Instead, when you add, update or delete a file, you must inform Git that you want that file tracked and saved as part of the next commit.

That’s where the git add command comes in.

How does the git add command work?

The git add command tells Git to include the updated state of a specific file the next time an explicit commit operation is performed.

Locate the git index in the root of the repo’s hidden .git folder.

Once a commit occurs, the state of all files added to the index are made part of the commit, and the index is wiped clean. As the developer adds, updates and deletes files, they must again perform a git add command to make those changes part of the next commit.

How to stage a file with git add

To stage a file with git add , follow these steps:

1. Add, edit or update a files in your project.
2. Perform the git add <filename> command to stage a file. (For multiple files, use git add . or git add -all .)
3. Perform a git commit operation.
4. Repeat.

A git add command example

Here’s a quick example of how the git add command works, from the creation of a new repository right through to the commit.

$ git init
Git repository created

$ touch alpha.html
$ git status
Untracked files: alpha.html

$ git add alpha.html
$ git status
Changes to be committed:
  new file: alpha.html

$ git commit -m "1st commit"
[master (root-commit) ee335da] 1st commit

$ git status
On branch master: Nothing to commit

Untracked files present error

If a developer attempts to perform a commit without having staged any files, the following error occurs:

 nothing added to commit but untracked files present.

The solution? Simply perform the git add command to stage any updated files and perform the commit again.

$ git commit -m "git add error example"
Untracked files: beta.html
Nothing added to commit but untracked files present
$ git add beta.html
$ git commit -m "now it should work"
[master (root-commit) ee335da] now it should work

Forget git add and you will see the ‘nothing added to commit’ error.

What does git add . do?

Many git add examples show how to add one file to the index at a time, but in practice a developer includes many changes in a commit.

To stage multiple files at the same time the developer can use the --all or -A switch.

$ git add -A
$ git add --all

You’ll also commonly see a single dot after git add. This performs the same function as the --all switch.

$ git add .

A single dot or period is common nomenclature in the Unix world that means, ‘The current folder.’

So a git add . command essentially tells git to stage every updated file in this current folder and all subfolders as well.

The git add command, when used with a dot, adds all modified files to the staging index.

What is in the current git index?

Sometimes you lose track of which files in your project are updated, and which of those files are added to the index.

To find out what is in the index, just issue a git status command and see everything you need to know about the status of files you have updated.

The git status command reports on any file in your repository that possesses any of these states:

• Modified;
• Deleted;
• Untracked; and
• Renamed.

Remove staged files from the Git index

If you’ve added a file to the index and you decide you do not want that file to be part of the next commit, simply run the following command:

git rm --cached <filename>

If you want to just clear the contents of the index completely, you can do a mixed git reset:

git reset --mixed

Why must we use the git add command?

Developers new to Git are often a bit stumped by the need for a Git index.

After all, why must we stage files? Why not just automatically add every updated file to the next commit and skip the Git index shenanigans?

In my many years of working with Git, I can’t come up with a really good answer to that question, other than to say it gives a developer more control over what files are added to a given commit.

Of course, that’s not really an answer. It really just repeats the purpose of the git add command.

Combine git add and commit together

For those who want to skip the ceremony associated with the git add command, you can use the -a switch on the git commit command:

git commit -am "new commit"

Unfortunately, this approach has limitations. While it adds updated and deleted files to the index before a commit, it ignores any newly created files.

Git GUI tool

For those that prefer to avoid the command line, a standard Git install comes with a GUI tool that allows you to perform git add and git commit commands through the click of a button.

Simply open the Git GUI tool in your project folder and select rescan.

The Git GUI tool lists any untracked, deleted or modified files, which you can select and stage by clicking the stage button.

Once done, add a message and click Commit. This enables you to perform stage and commit files without having to master the command line or the Git BASH tool.

The Git GUI tool allows you to perform the git add command graphically.