The git add command for beginners

What does the git add command do?

The git add command is used to select the files to be included in the next git commit.

Git will 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 that happen to files and folders in your software project over time.

However, Git doesn’t behave like the autosave feature in Microsoft Word. 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.

How does the git add command work?

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

The git index can be found 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 have those changes made part of the next commit to take place.

How to stage a file with git add

To stage a file in git and , follow these steps:

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

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 an 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?

In many git add examples you’ll seen one file added to the index at a time, but in practice a developer will include 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 for ‘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, will all modified files to the staging index.

What is in the current git index?

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

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

The git status command will report one any file in your repository that possesses any of these states:

• modified
• deleted
• untracked
• 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 made part of the next commit, you 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 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’s really just repeating what the purpose of the git add command is.

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 does have limitations. While it will add updated and deleted files to the index before a commit, it will ignore 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 will list 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 allows 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.