Split work into focused commits
One file has a bug fix mixed with unrelated refactoring. Use git add -p to stage only the fix hunks and commit them first.
Git · Command
git add
git add copies the current content of new or changed files into the index (the staging area), which holds what the next commit will contain. A plain git commit records only what has been staged.
Last updated
How it works
The index sits between your working tree and your commit history. When you run git add, Git stores the file's content as it is at that moment and points the matching index entry at it. Later edits to the file are not staged until you run git add again. Pathspecs choose which files are affected. Naming a directory makes the index match that whole directory, including files added or deleted in it. Options control the details: -u updates only files Git already tracks, -A covers all files, -p lets you pick individual hunks, and -N records an empty placeholder entry.
Syntax
git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--edit | -e] [--[no-]all | -A | --[no-]ignore-removal | [--update | -u]] [--sparse] [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--renormalize] [--resolved] [--chmod=(+|-)x] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]Parameters
| Name | Type | Description |
|---|---|---|
<pathspec>... | pathspec | The files to stage. Accepts file globs such as *.c and directory names. Naming a directory stages new, modified and deleted files inside it. |
-n, --dry-run | flag | Lists what would be added or ignored without changing the index. |
-f, --force | flag | Stages files that would otherwise be ignored. Also stages a submodule update when that submodule is set to ignore=all. |
-p, --patch | flag | Lets you choose, hunk by hunk, which changes between the index and the working tree to stage. |
-i, --interactive | flag | Opens the interactive menu (status, update, revert, add untracked, patch, diff). |
-e, --edit | flag | Opens the diff against the index in your editor and stages the patch you save. |
-u, --update | flag | Updates only paths the index already tracks, staging their modifications and deletions but never adding new files. |
-A, --all | flag | Makes the index match the working tree by staging additions, modifications and deletions. |
--no-all, --ignore-removal | flag | Stages new and modified files but leaves files deleted from the working tree alone. |
-N, --intent-to-add | flag | Records that the path will be added later by placing an entry with no content in the index. |
--renormalize | flag | Runs the clean filter again on all tracked files, for example to fix line endings. Implies -u. |
--resolved | flag | Marks unmerged paths as resolved when no conflict markers remain in them. Cannot be combined with -u or -A. |
Key points
- Staging records a snapshot. If you edit a file after adding it, the staged version stays the old one until you run git add on it again.
- -u works only on files Git already tracks. It stages their edits and deletions, but untracked files stay untracked.
- -A brings the index fully in line with the working tree, covering new, changed and deleted files.
- -p lets you stage only some of the changes in a file, hunk by hunk, so one file's edits can go into separate commits.
- -N adds a placeholder entry for a new file. This makes the file show up in git diff and lets git commit -a include it.
- --chmod=+x marks a file as executable in the repository without touching its permissions on disk. This is handy on file systems that cannot store the executable bit.
- --renormalize stages tracked files again through the clean filter. Use it after changing core.autocrlf or the text attribute.
Common mistakes
- Ignored files behave differently depending on how you name them. If you name an ignored file exactly, git add fails with an error. If it only matches a glob or sits inside a directory you added, it is skipped without any message.
- Whether you quote a glob matters. If the shell expands it, only matching files in the current directory are staged. If Git expands it, matching files in subdirectories are included too.
- --ignore-errors keeps adding the other files when some fail, but the command still exits with an error code, which scripts should check.
- When editing patches by hand with -e, it is easy to make a patch that cannot be applied to the index.
Example: Stage selectively, then commit
#!/usr/bin/env bash
set -euo pipefail
# Preview what would be staged
git add --dry-run src/
# Stage one file completely
git add README.md
# Pick individual hunks from a file you edited
git add -p src/app.py
# Stage edits and deletions of tracked files only (no new files)
git add -u
# Mark a script as executable in the repository only
git add --chmod=+x scripts/deploy.sh
# Quote the glob so Git also matches files in subdirectories
git add 'docs/*.md'
# Review the staged changes, then commit them
git diff --cached --stat
git commit -m "Update docs and app logic"The script previews what would be staged, stages files in several different ways, checks the staged result with git diff --cached, and then commits it.
When to use it
Finish a merge after resolving conflicts
After removing the conflict markers by hand, run git add (or git add --resolved) on those paths to mark them resolved before you commit the merge.
Fix line endings in the repository
After changing core.autocrlf or .gitattributes, run git add --renormalize . so every tracked file is stored with the corrected line endings.
Stage a large or generated list of paths
Write the paths to a file, or pipe them in with --pathspec-from-file=- and --pathspec-file-nul, so the command line does not get too long.
Interview questions
QHow do git add ., git add -u and git add -A differ?
git add . stages new, modified and deleted files under the current directory, because a directory pathspec makes the index match that directory. -u touches only files already in the index, so it stages edits and deletions but never new files. -A stages additions, edits and deletions, and with no pathspec it applies to the entire working tree.
Follow-up: What does --no-all do? It stages new and modified files but skips deletions, which is how older Git versions behaved, and it does nothing if you give no pathspec.
QYou run git add on a file, edit it again, and then commit. What gets committed?
The version you staged, not the later edit. git add copies the file's content at the moment you run it, and a plain git commit records only the index. git status will list the file as both staged and modified.
Follow-up: How do you include the newer edit? Run git add on the file again before committing, or use git commit -a, which updates the index with all changes to tracked files before committing.
QWhat does git add -N do, and why use it?
It records only an intent to add the file: an index entry with no content. The file then counts as tracked, so git diff shows its contents as unstaged changes and git commit -a will include it.
Follow-up: How is that different from git add -p on a brand-new file? -p offers hunks only for differences between the index and the working tree, so add the new file with -N first, and then -p can stage parts of it.
Related
git statusgit commitgit diffgit resetgit restoregit rmgit mvgit update-index