Command Reference

git add Tutorial

Explains how git add stages changes for the next commit, how patch staging works, and how to avoid mixing unrelated edits into one commit.

Who This Is For

Developers who already know basic commit and branch actions
Readers who want to understand command boundaries and risk

Prerequisites

A basic mental model of worktree, index, and commits
Comfort reading `git status` and a small commit graph

Common Risks

Using local cleanup commands on already shared history
Continuing to rewrite before confirming a recovery path

The short version

git add copies selected content from the working tree into the index so the next commit can use it.

Think in layers, not files alone

git add does not “save your work” by itself. It updates the staging snapshot. That is why the same file can still have unstaged edits even after you run git add.

What problem this command actually solves

New Git users often assume a commit is built directly from current files.
Git is stricter than that: it asks you to decide which content belongs in the next commit first.

That extra step is what makes these workflows possible:

split one messy working session into several logical commits
stage only the lines that are ready for review
leave half-finished experiments out of the next commit
resolve conflicts and stage only the resolved files

The forms you will actually use

git add README.md
git add src/
git add .
git add --patch

git add README.md: stage one file
git add src/: stage a directory
git add .: stage all detected changes under the current directory
git add --patch: stage selected hunks interactively

A realistic daily workflow

The safest everyday loop is usually:

inspect the current state with git status
inspect the actual changes with git diff
stage intentionally with git add <path> or git add --patch
confirm the staged result with git diff --staged
commit only after the index looks right

For example:

git status
git diff
git add --patch
git diff --staged
git commit -m "fix: keep search fallback stable"

Use the index as a quality filter

If a commit should tell one story, the index is the place where you enforce that story before it becomes history.

Where people get into trouble

The most common mistake is not syntax.
It is staging more than intended because git add . felt convenient.

Typical failure patterns:

staging debug output, generated files, or unrelated refactors together
assuming a file is fully staged when only part of it should be
forgetting that new edits made after git add are still unstaged
resolving a conflict but forgetting to stage the resolved file

Patch mode is the skill that changes everything

git add --patch

Patch mode matters because it lets you separate:

one bug fix from a nearby refactor
production code from temporary logging
finished changes from still-uncertain edits

That is often the difference between:

a commit that is easy to review
and a commit that future-you cannot safely revert or cherry-pick

How to reason about staged versus unstaged edits

Imagine you modify the same file twice:

first you change the real logic
then you add temporary console output
you run git add --patch and stage only the logic change

Now the file exists in two states at once:

the index contains the logic fix
the working tree still contains the temporary logging

That is not weird Git behavior.
That is exactly what the index is for.

Diagram view

Working tree to index to commitThe key decision is whether you are only changing files, staging a snapshot, or turning that staged snapshot into history.

Current state

Working tree editsIndex snapshotCurrent branch

What changes

Updated indexReviewable staged diffSafer next commit

If you are unsure what changed, compare `git diff` and `git diff --staged` before committing.

Boundaries worth remembering

git add usually does not move branch pointers, but it absolutely changes what the next commit will mean.
git add . is fast, not careful. Prefer narrower staging when the change set is mixed.
If you are about to switch branches or recover from mistakes, a clean understanding of what is staged versus unstaged matters a lot.

Do not confuse staging with backup

Staging content does not publish it anywhere. It only changes the local index. If you need a recovery point, create a commit or a stash rather than assuming staged changes are “safe enough”.

Try it yourself

Exercise: create one clean commit from a messy edit session

This exercise helps you feel the difference between the working tree and the index.

Setup

git switch -c lab/add-demo
# edit one file with both a real fix and a temporary debug line

Try it

Run `git diff` to see all edits.
Run `git add --patch` and stage only the real fix.
Run `git diff --staged` and confirm the staged change is clean.
Leave the debug line unstaged and create the commit.

What happens next

The commit contains only the staged change.
The working tree can still keep extra unstaged edits.
You end up with cleaner history without losing the unfinished work.

Common mistake checks

If `git diff` looks empty, check `git diff --staged` because the change may already be in the index.
If your commit still contains mixed work, you probably staged too broadly.
If you resolved a conflict, remember that the resolution is not complete until the file is staged.

Previous / Next

Previousgit status TutorialCommands Nextgit commit TutorialCommands