Git Add: Staging Changes for Your Next Commit
The git add command moves changes from your working directory to the staging area, also known as the index, preparing them for your next commit. This command is used to take a snapshot of specific file modifications, marking them as ready to be permanently recorded in the repository’s history.
Understanding git add is fundamental to effective version control with Git. It provides the crucial intermediate step between making changes and committing them, allowing you to fine-tune exactly what goes into each commit.
What is the git add Command?
The git add command is a core component of Git. It stages modifications. When you edit files in the working directory, Git sees these changes as unstaged. Running git add on a file tells Git, “Include the current state of this file in the next commit.” This action places a copy of the file’s content into the staging area.
It’s important to clarify that git add does not save files permanently or directly alter the repository’s history. Its sole purpose is to populate the staging area. Many beginners confuse git add with git commit. They think git add saves their work. However, git commit permanently records the staged changes in the repository, as Google’s current facts note. Developers often think of the staging area as a temporary holding space. Here, they assemble the exact set of changes for the next logical commit.
Why Use a Staging Area?
The staging area provides a powerful mechanism for creating precise, logical commits. You can stage only related modifications. Do not commit all changes in the working directory at once. For example, if you are fixing a bug and also refactoring some unrelated code, you can stage the bug fix changes first. Commit them, and then stage and commit the refactoring changes separately. This keeps the commit history clean. It also makes it easier to revert specific changes if needed.
How to Use git add Effectively
Using git add involves specifying which files or directories are to be staged. There are several common patterns relied on, each suited for different scenarios.

git add <file>
This is the most basic usage. It stages the changes for a single, specified file. For example, if index.html and style.css have been modified, and only index.html is to be staged, one would run:
git add index.html
Adding Multiple Files
To stage several specific files, you can list them one after another:
git add file1.txt file2.js README.md
This command stages the changes for all three specified files, allowing me to prepare a commit that includes only these particular modifications.
What Does git add . Do?
Developers frequently use the command git add .. However, it’s crucial to understand its behavior. It stages all changes in the current directory and its subdirectories. This includes new untracked files, modified files, and deleted files. You typically use this when you are confident that all changes in the current working directory are related. They should be part of the same commit.
git add .
While convenient, using git add . can be problematic if you have temporary files or changes that belong to different logical units, potentially staging unwanted content, as highlighted by Google’s current facts. Always use git status before and after running git add . to ensure you’re staging only what you intend.
Using git add -A and git add -u
Git offers options to stage changes more broadly or selectively:
git add -A(orgit add --all): This command stages all changes across the entire repository. It does this regardless of your current directory. This includes new files, modified files, and deleted files. It’s similar togit add ., but it operates from the root of the repository. This makes it solid for ensuring you catch all relevant changes.git add -u(orgit add --update): This command stages changes only for files that Git already tracks. It specifically stages modifications and deletions. However, it will not add new, untracked files. You find this useful when you are only refining existing code. No new files have been introduced in this case.
Here’s a quick comparison of these common staging commands:
| Command | What it Stages | Scope | Use Case |
|---|---|---|---|
git add <file> |
Specific file modifications | Specified file only | Precise staging of individual files. |
git add . |
New, modified, and deleted files | Current directory and subdirectories | Stage all relevant changes in a specific working area. |
git add -A |
New, modified, and deleted files | Entire repository | Stage all changes across the project. |
git add -u |
Modified and deleted files (tracked only) | Entire repository | Stage changes to existing files, ignore new untracked files. |
When to Use git add
You use git add whenever you have made changes that you want to group into a single commit. The primary benefit is its role in selective staging. This allows you to craft meaningful commit messages and maintain a clean project history.
Consider a scenario where you have worked on a new feature. You have also tweaked some configuration files and fixed a typo in a documentation file. Instead of committing all these disparate changes together, you would take the following actions:
- Stage only the new feature files:
git add src/new_feature.js public/feature.html - Commit the new feature:
git commit -m "feat: Implement new user profile page" - Then, stage the configuration file changes:
git add config/settings.yml - Commit the configuration update:
git commit -m "chore: Update database connection settings" - Finally, stage the documentation fix:
git add docs/README.md - Commit the documentation fix:
git commit -m "docs: Fix typo in README"
This approach ensures that each commit represents a single, logical change, making it much easier to review, revert, or understand the project’s evolution.

If git add Still Fails or Behaves Unexpectedly
Sometimes, git add might not work as expected or produce errors. Here are common reasons and their solutions:
Ignored Files Not Being Added
By default, git add will not add files that are listed in your .gitignore file. If you are trying to add a file that you know is ignored, and you specifically want to track it, you can use the --force option:
git add --force path/to/ignored_file.log
You use the --force option only when you genuinely intend to track a file. This applies to previously ignored files, like an empty .gitkeep file or a specific configuration that needs versioning.
Permissions Issues
If Git doesn’t have the necessary permissions to read or write files in your working directory or the .git repository, git add can fail. This is more common in shared environments or when working with files created by different users.
- Check file permissions: Use
ls -l(Linux/macOS) or check file properties (Windows) to verify that your user has read/write access to the files you’re trying to stage and the.gitdirectory. - Adjust permissions: You might need to use
chmod(Linux/macOS) to grant appropriate permissions.
File Indexing Errors
Although rare, Git can encounter indexing errors. These often occur in corrupted repositories or after system crashes. Historically, you could set the configuration variable add.ignoreErrors to true to continue adding files despite these errors. However, this variable is now deprecated. If you encounter persistent indexing errors, we recommend trying to recover the repository. Alternatively, clone a fresh copy if possible.
How to Confirm Changes are Staged
After you run git add, always verify that you have moved the intended changes to the staging area. Use the git status command for this. This command provides a clear overview of the working directory and staging area.
git status
When you run git status after successfully staging changes, you should see the files listed under a section titled “Changes to be committed.” For example:
On branch main
Your branch is up to date with 'origin/main'.
Changes to be committed:
(use "git restore --staged <file>..." to unstage)
new file: new_feature.js
modified: index.html
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: style.css
Untracked files:
(use "git add <file>..." to include in what will be committed)
temp.log
In this output, you have correctly staged new_feature.js and index.html. style.css has further modifications that you have not yet staged. temp.log is an untracked file. This allows you to confirm the state of the repository before you proceed to commit.
Related guides
Frequently Asked Questions
What does git add do?
The command git add works similarly to git add . in most shell environments. It expands to all files and directories in the current directory, then stages them. However, git add . is generally preferred for clarity and consistency across different shell interpretations.
Why is git add an important step?
git add is an important step. It allows you to selectively choose which changes to include in your next commit. This selective staging enables you to create logical, focused commits. This makes your project history cleaner, easier to understand, and simpler to manage or revert specific changes.
Can I unstage files after using git add?
Yes, you can unstage files after using git add. To move a file from the staging area back to the working directory, you use git restore --staged <file>. This effectively undoes the git add command. For example, to unstage index.html, you would run git restore --staged index.html.