git add

Summary: git add <path> stages the current content of the file(s) at <path>: new files start being tracked, edits and deletions are recorded in the staging area, ready for the next commit.

Safe — it never edits a file and never creates a commit; anything staged can be unstaged with git restore --staged.

What it does

Copies the file's content as it is right now into the index (the staging area). For an untracked file, that starts tracking it; for a modified file, it records the new content; for a deleted file, it records the deletion. The working tree is untouched.

Why it exists

So that a commit contains exactly what you choose, not everything you happened to touch. Staging is the review step between editing and recording.

When to use it

• Before every commit, for each file (or hunk) that belongs in it.
• To start tracking a new file.
• To stage a deletion or a rename done in the editor (stage both old and new paths).

When not to use it

• On generated files, dependencies, secrets: .gitignore should be catching them. Git refuses ignored files unless you force it; do not.
• With . before reading git status.

Syntax

Examples

$ git status -s

 M README.md
 M docs/faq.md
?? docs/notes.md

$ git add docs/faq.md
$ git status -s

 M README.md
M  docs/faq.md
?? docs/notes.md

$ git add .
$ git status -s

M  README.md
M  docs/faq.md
A  docs/notes.md

Part of a file:

$ git add -p README.md

diff --git a/README.md b/README.md
index 19ed536..6516ba6 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Trailguide
 
-A tiny command-line program that prints hiking trail information for the **Northwind Trails** guide.
+A small command-line program that prints hiking trail information for the **Northwind Trails** guide.
 It exists so that people learning Git have something realistic to practice on: documentation to edit,
 data to update, a small program to run, and tests that can pass or fail.
 
(1/1) Stage this hunk [y,n,q,a,d,e,p,?]? 

An ignored file is refused:

$ git add .env

The following paths are ignored by one of your .gitignore files:
.env
hint: Use -f if you really want to add them.
hint: Disable this message with "git config set advice.addIgnoredFile false"

Expected result

git status moves the file to "Changes to be committed" (first column of -s); git diff --staged shows its content; git diff no longer shows it. Nothing is committed yet.

Try it here

The simulator below runs a small model of Git in the page. Nothing here touches a real repository, so try the command, then try it wrong (lesson 2.8 explains it).

Common mistakes

• Editing after adding. The staged copy is the old one; the file appears in both groups. Add again.
• git add . picking up stray files. Read the status first; unstage extras with git restore --staged <file>.
• Adding a folder with a generated subfolder. Fix .gitignore, then git rm --cached what slipped in.
• Expecting add to save the work. It only stages; commit to record.

How to undo or recover

git restore --staged <file> removes it from the staging area, keeping the edit. Before the first commit, the hint says git rm --cached <file> instead; same effect.

In VS Code

The + next to a file (stage), next to the Changes heading (stage all), or Stage Selected Ranges in a diff for part of a file. See Staging with git add.

In IntelliJ IDEA

Tick files in the Commit tool window (staged at commit time), or enable the staging area in settings for explicit + icons; hunk checkboxes in the diff viewer for partial staging.

Related commands

git status shows what can be staged · git diff shows what you are about to stage · git restore unstages · git commit records what was staged · git rm and git mv stage deletions and renames directly.

Lessons that use this command

Staging with git add · The four areas · Lab 1.