A commit run with no extra arguments records what the index holds and nothing else. git add is the command that puts content there. It copies new or changed files into the index, also called the staging area, which sits between the working directory and the commit history.
Pro Git calls it a multipurpose command. It starts tracking new files and stages edits to tracked ones. It also marks a file caught in a merge conflict as resolved.
The index keeps each file as it looked when the command ran. Edit the file afterward and that edit stays out of the next commit until you run the command again, so the same file then shows up as both staged and unstaged. It trips up plenty of people.
What Does git add Do?
Whatever you add goes into the index, and the next commit records exactly that content. Think of the index as the draft of your next commit.
Run git commit with no other arguments and it records only what sits in the index (Git manual). Edits you never staged stay in the working directory and miss the commit.
Pro Git describes the command as multipurpose. It begins tracking an untracked path the first time you add it. After that it stages edits to tracked files, deletions included, and it marks files from a merge conflict as resolved.
The book suggests reading the command as adding “precisely this content to the next commit” instead of adding a file to the project.
Nothing reaches history yet, since Atlassian’s tutorial notes that git add changes the repository very little until a commit happens. The index is what Git calls staging, a holding area between the working directory and the commit history.
How git add Stages Changes Before a Commit
git add captures a file exactly as it looks when the command runs.
Edit the file afterward and the index still holds the older version.
Pro Git has a worked case. Stage CONTRIBUTING.md, then edit it again, and git status lists the file twice, under “Changes to be committed” and under “Changes not staged for commit”.
git status -s shows MM for a file in this state, meaning modified in the index and modified again in the working tree (Pro Git’s short-status example). A commit at this point records the staged version, not the newer edit.
Run git add on the file again and the latest version replaces the staged one. The manual confirms the command can run as many times as needed before a commit.
Subversion users trip on this. Atlassian draws the line clearly. svn add registers a file once, while git add works on changes and repeats after every edit.
The basic staging loop goes like this.
- Create or edit the file.
- Run
git add <file>. - Run
git statusand confirm the path sits under “Changes to be committed”. - Run
git committo record the snapshot.
Running git status before every commit catches the staged-then-edited case, because both lists appear in one output.
Once the index looks right, git commit writes the staged snapshot to history and moves the current branch pointer up to it (Pro Git).
git add Syntax and Options
The synopsis is git add [options] [--] [pathspec...], and the pathspec decides which paths the index updates.
| Option | Effect | Use it when |
|---|---|---|
-n / --dry-run | Shows what would be added or ignored, stages nothing | A broad pathspec needs a preview |
-v / --verbose | Prints each file as it is added | A large add needs an audit trail |
-f / --force | Adds files that .gitignore would skip | An ignored file must be tracked on purpose |
-N / --intent-to-add | Records the path with no content | A new file should appear in git diff |
--ignore-errors | Keeps adding other files when some fail | One unreadable file blocks a big batch |
--chmod=+x | Sets the executable bit in the index only | A script needs its mode fixed without touching disk |
The scope flags (-u, -A) and the interactive modes (-p, -i, -e) have their own sections further down.
Selecting files with pathspec
A file name stages that file, and a directory name stages everything under it recursively, removed files included. A glob such as *.c stages every matching file.
Quoting decides which files a glob reaches. In the manual’s example, git add Documentation/\*.txt passes the asterisk to Git, so files in subdirectories match too.
Leave it unquoted, as in git add git-*.sh, and the shell expands the pattern first. Then subdir/git-foo.sh is never considered.
A double dash separates options from file names that look like options.
What -N (intent to add) records
The flag places an entry for the path in the index with no content. It records only the fact that the path will be added later (Git manual).
That entry lets git diff show the unstaged content of a brand-new file, and lets git commit -a commit it.
Plain git add stages content at once. -N covers the in-between state.
git add . vs git add -A vs git add -u: Which Should You Run?
Run git add -A to stage every change in the repository, git add -u to stage tracked files only, and name paths when the commit must stay narrow.
| Command | Stages | Scope |
|---|---|---|
git add . | New, modified and deleted files | Current directory and below |
git add -A | New, modified and deleted files | Entire working tree |
git add -u | Modified and deleted tracked files, no new ones | Entire working tree |
git add <path> | Content at that path, removals included | Named paths only |
From the repository root, . and -A give the same result in Git 2.0 and later. Sentry’s explainer states this only for the case where no files were deleted, which reflects the pre-2.0 rules. The difference now shows up when you run them from a subdirectory.
Git 2.0 changed how these commands behave, as announced in the Git 1.8.3 release notes.
git add <path>started acting likegit add -A <path>, sogit add dir/records files removed from the directory. Earlier versions ignored removals.git add -uandgit add -Awith no pathspec began covering the entire tree from inside a subdirectory, matchinggit commit -a.
The --ignore-removal option (also spelled --no-all) brings back the old treatment of removed files. The Git 2.56.0 manual still documents both.
Tutorials disagree on deletions. GeeksforGeeks lists deletions as something plain git add leaves unstaged, while the current manual says a pathspec updates the index to match the working tree, removals included. The manual reflects the Git 2.0 change, so a page saying otherwise describes older behavior.
For a deleted file, git rm stages the removal in one step. Running git add on the missing path now does the same job.
Sweeping commands stage whatever is not ignored. Without a complete .gitignore file, git add -A pulls in build output and log files, the kind of generated files Pro Git warns about.
If only tracked files changed, git add -u does the job.
When new files belong in the commit and you are at the root, git add -A covers them too. A narrow commit calls for naming the paths, or for git add -p when one file holds unrelated edits.
Staging Part of a File With git add -p
git add -p walks through the diff hunk by hunk and stages only the hunks you approve.
The command jumps straight to the patch subcommand of interactive mode and skips the main menu (Git manual). That menu holds 6 subcommands plus help and quit: status, update, revert, add untracked, patch and diff.
Pro Git shows what partial staging leaves behind. lib/simplegit.rb reports +1/-1 staged and +4/-0 unstaged, so a commit takes only the staged lines.
Hunk commands you will use most
ystages the hunk andnskips itssplits the current hunk into smaller oneseopens the hunk for editing by handastages this hunk and every later hunk in the file, whiledskips them allqquits without staging this hunk or the remaining ones
The sources disagree on how many responses exist. Pro Git’s help output lists 13, while the current Git manual lists 16, adding q, p and P.
Trust the manual, and press ? at the prompt to see what your installed version offers. Setting interactive.singleKey to true removes the Return keypress after each answer.
Editing a hunk with e
The editor opens the hunk as a patch, and the edited result is applied to the index.
Delete a “+” line to keep that addition out of the index. Turn a “-” into a space to keep that removal out of the index. Delete every line and nothing gets staged.
Edits touch the index only, so the working directory appears to undo any line you invent. The manual says to avoid the exotic constructs or use extreme caution.
A brand-new file needs git add -N first. The git reset manual’s split-a-commit example relies on the same intent-to-add idea, using git reset -N, so that git add -p finds new files.
Pro Git adds that patch mode also exists for git reset and git checkout, and for stashing with git stash.
How to Check and Undo Staged Changes
Check staging with git status and git diff --staged, then unstage with git restore --staged <file> or git reset <file>.
git status lists staged and unstaged paths by name. git diff compares the working directory with the index, so it shows unstaged edits only. To see what is staged, use git diff --staged, which compares the index with the last commit (--cached is a synonym).
Once everything is staged, git diff prints nothing, according to Pro Git. People read that silence as “no changes” and are wrong.
Some commands only touch the index.
git restore --staged <file>resets the index entry to HEAD and leaves your edits on diskgit reset <file>does the same job, and the manual calls the two equivalentgit reset -punstages hunk by hunk, the mirror ofgit add -p
Others reach into your files.
git restore <file>without--stagedrewrites the working copy from the index and discards unstaged editsgit restore --staged --worktree <file>resets both the index and the working copy to HEAD
One missing flag turns a harmless unstage into data loss. Type --staged every time.
git add does not remove files from staging. It stages deletions, which is a different job.
The git restore command first appears in the 2.23.0 manual (August 2019), so git reset is the fallback on older installs. For the single-file case, this guide on unstaging a file in Git walks through both forms.
Inside git add -i, the revert subcommand returns a path’s staged state to the HEAD version, and reverting a new path leaves it untracked (Git manual).
When git add Does Not Stage a File
git add skips a path when an ignore rule matches it, sparse-checkout excludes it, or the command in use never adds new files.
Ignored files are skipped by default. Naming the exact file makes git add fail with a list of ignored files, while a broader pathspec skips it without a word (Git manual).
Sparse-checkout is stricter. git add refuses to update paths outside the cone, because those files could be removed from the working directory without warning, and the --sparse flag overrides the refusal.
A nested repository triggers a warning unless it was added through git submodule add. The --no-warn-embedded-repo flag silences it.
After a change to core.autocrlf or the text attribute, wrong line endings can linger in tracked files. --renormalize re-stages them with the corrected endings.
A new file left out of a commit usually traces back to git add -u. Pro Git shows the symptom: “nothing added to commit but untracked files present”.
When some files cannot be indexed, git add stops. The --ignore-errors flag adds the rest and still exits non-zero, and add.ignoreErrors makes that the default.
When a path refuses to appear, run git add -n on it. The dry run reports whether the path exists and whether it would be ignored.
Check the ignore rule before reaching for -f.
Common Questions About git add
Can git commit -a replace git add?
Only for files Git already tracks. The -a flag stages every modified tracked file before the commit, but new files still need git add.
Pro Git warns that the shortcut can pull unwanted changes into the commit.
Is git stage the same as git add?
Yes. The Git manual documents git stage as a synonym for git add and points readers to the git add page for details.
Pick one spelling and keep it consistent across a team.
How do I add an empty directory with git add?
You cannot. Git tracks files, and git add on a directory stages the files inside it recursively (Pro Git), so an empty one yields nothing.
Put a placeholder file inside it, such as .gitkeep. The name is a community convention, not a Git feature.
Does git add upload my changes to GitHub?
No. git add updates only the local index.
Changes reach a remote such as GitHub or GitLab after git commit records them and git push publishes the commit.
What to Do After You Stage Changes
The order after git add matters. Review the index with git diff --staged, commit the staged snapshot, then push the commit to the remote.
Review comes first because staged edits have no protection yet. A git reset –hard HEAD discards them, and only a commit makes staged work survive that command (Git manual).
Once the commit exists, pushing the commit to GitHub or GitLab shares it with the team.
The advice was verified against the Git 2.56.0 manual on October 1, 2026. A change in how git commit or git reset treats the index would reorder these steps.
- How to Turn On Dark Mode in Notepad++ (Built-In, No Plugin) - October 3, 2026
- PostgreSQL Cheat Sheet - October 2, 2026
- How to Repair a Corrupt SQL Server Database Without Any Data Loss - October 2, 2026
