git add: put changes into the index

git add moves changes from the working directory into the index (staging area), the set that goes into your next commit as a whole.

On its own git add saves nothing permanently. It picks: these edits I am ready to record, the rest can wait. The saving is done by git commit.

$ git add recipe.txt                 # one file
$ git add recipe.txt steps.txt       # several at once
$ git add notes/                     # a whole directory

Check the result with git status: what you picked gathers under the Changes to be committed heading.

$ git status
On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	new file:   steps.txt

The way back is printed in the parentheses. git restore --staged steps.txt takes the file out of the index without touching a single line inside it.

git add . and why it bites

The dot means "everything that changed in the current directory and below". The command saves typing, and it also drags into the history things that do not belong there: drafts, a password saved by accident, a one-gigabyte database dump, a dependency folder with a hundred thousand files.

The habit is simple: after git add . run git status and read the list with your own eyes. Junk that never belongs in the repository is better listed in .gitignore, so git stops noticing it at all.

Staging piece by piece

When one file holds edits from two different tasks, git add -p offers them in chunks:

$ git add -p recipe.txt
@@ -1,2 +1,3 @@
 line1
 line2
+milk
(1/1) Stage this hunk [y,n,q,a,d,e,p,?]?

y takes this chunk, n skips it, q quits, and ? explains the remaining letters. On a large chunk you also get s, which cuts it into smaller pieces. That turns one file into two meaningful commits instead of one pile.

Common mistakes

An edit made after git add does not reach the index. The index holds the content of the file as of the moment you ran the command, so a file can show up twice in git status: under Changes to be committed and under Changes not staged for commit. Run git add again to fix it.

Second: git add never rolls back or deletes anything in the working directory. It only copies the state of a file into the index.

Where this is in the book

The topic is covered in Chapter 3. Three areas and your first commit.

To practise it by hand, take the interactive lesson Three areas and a commit.