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.
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:
- Add, edit or update a files in your project
- Perform the git add <filename> command to stage a file
- Optionally use git add . or git add -all for multiple files
- Perform a git commit operation
- 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
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.
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.