Staging in Git is the process of selecting which changes you want to include in the next commit. When you stage a file with git add, Git stores a snapshot of that file in the staging area (also called the index) and prepares it to be committed.
In this tutorial, you will learn to use git add to stage files in Git.
Prerequisites
- Git installed (install Git on Windows, macOS, or Ubuntu).
- A working Git repository.
What Is git add?
The git add command includes changes from your working directory into Git's staging area, preparing them for the next commit. By specifying which file(s) to add to the staging area, the user lets Git know which files to record in the index.
The command provides fine-grained control as you can stage only some files, certain parts of a file, or stage everything at once. That level of control ensures your commits capture only the changes you intend.
In addition to adding files to the staging area, git add also reshapes the commit history before actually committing. For example, you can add files in logical groups, such as one commit for documentation updates and another for code refactoring, even if the changes happen simultaneously. The control in staging and committing separation facilitates cleaner and more meaningful commits.
How Does git add Work?
The git add command works by taking the current content of the specific files and writes that content into Git's object database as blob objects. Each blob has a unique a SHA-1 hash calculated from the file contents.
Once it creates the blob (or confirms it already exists), Git updates its index file. The index file is a binary data structure living in .git/index, and its purpose is to record that the next commit should reference these blob hashes. Essentially, the index maps file paths to blob IDs, along with metadata like file mode and last modification time.
Staging a file with git add does not create a new commit but only updates the index so that the next git commit operation bundles together exactly those blob versions. If you modify a file again after staging but before committing, you must run git add again to update the index with the new blob.
For deleted files, git add removes their entries from the index. Interactive staging modes (e.g., -p or --patch) go a step further by breaking a file's changes into hunks and allowing the user to choose which hunks to write into the index.
How to Use git add
To use git add, first make sure you are inside an existing Git repository and have at least one new or modified file. To check which files in your repository are untracked or have changes, run the following command:
git status
The command's output shows the current state of your working directory and the staging area (index). If you have a .gitignore file, any paths there will be skipped by git add.
When you decide which files to stage, you need to decide on how to stage them. Not every change you make belongs in the same commit. Use the staging area when you want to:
- Group related work. If you have fixed a bug in one file and tweaked styling in another, stage and commit them separately, so each commit has a single, clear purpose.
- Cherry-pick hunks. If you explored several ideas in one file but only want to ship one of them, use the
--patchoption to pick exactly which hunks to include. - Maintain a clean history. Smaller, focused commits make it easier to bisect regressions, roll back specific changes, and write meaningful commit messages.
Use the syntax below to stage files with git add:
git add [options] [path]- The
[options]are optional flags that tailorgit addprecisely to your workflow, allowing you to stage everything in one go or selectively pick which changes to stage. The available options are in the section below. - The
[path]is the path to the file or files you want to stage.
For example, to stage the index.html file, run:
git add index.htmlThe command adds the index.html file to the staging area and includes it in your next Git commit.
git add Options
Git's staging options let the user control exactly what changes to add to the index, when to add them, and how to do it. Use the options when you need fine-grained control over large sets of changes, want to avoid accidentally committing deletions, or need to enforce consistent line-ending rules across a project.
Below is a table of key git add options with their descriptions:
| Option | Description |
|---|---|
-n, --dry-run | Show which files would be staged without actually modifying the index. |
-v, --verbose | Display each file name as it is added, so you can see exactly what is being staged. |
-f, --force | Override ignore rules to stage files that match patterns in .gitignore or global ignore settings. |
-i, --interactive | Launch a menu-driven interface to review changes and selectively stage files or hunks. |
-p, --patch | Step through each diff hunk and manually choose which hunks to stage (skips the initial interactive menu). |
-e, --edit | Open the diff against the index in your editor, letting you edit or trim hunks before adding. |
-u, --update | Stage new and modified files, but ignore deletions. This option is useful if you want to avoid accidentally staging file removals. |
-A, --all | Stage all changes across the working directory. Add new files, update modified ones, and record deletions. |
--no-all, --ignore-removal | Stage new and modified files but ignore deletions. This option is useful if you want to avoid accidentally staging file removals. |
-N, --intent-to-add | Record the fact that a file will be added later by creating an empty index entry. It is useful to show unstaged changes via git diff. |
--refresh | Update the index's stat information (e.g., file timestamps or permissions) without changing which files are staged. |
--ignore-errors | Continue staging other files even if some files cause errors (e.g., permission issues). The command still exits non-zero if errors occur. |
--ignore-missing | (Only with --dry-run). Don't report missing files as errors. Only checks if the given paths would be ignored or not. |
--renormalize | Reapply Git's clean filters (e.g., line-ending normalization) to all the files you are tracking and update their content in the index. |
--chmod=(+|-)x | Override the executable bit of the added files. The executable bit is only changed in the index, the actual files are not changed. |
--pathspec-from-file=[file] | Read pathspec elements (files or patterns) from a file (or STDIN if it is given), rather than passing them on the command line. |
--pathspec-file-nul | When used with --pathspec-from-file, split pathspec entries on NUL characters so that names with special characters are handled literally. |
--no-warn-embedded-repo | Suppress warnings when adding a Git repository nested inside another repository. It is useful when manually managing submodules. |
The sections below exemplify some key options to use with git add.
Preview Which Files Would Be Staged: --dry-run
Use the --dry-run option to see exactly which files Git should add to the index without actually touching the staging area. The feature is helpful before a big commit to verify you have not missed anything or to check if Git will ignore certain files.
For example:
git add --dry-run *.js
The output shows which JavaScript files Git would stage, but it does not modify the index. This feature helps users see precisely which files would be staged if --dry-run was omitted.
Show Staging Details: --verbose
Include the --verbose (-v) option to print the name of every file as Git stages it. This option is useful when you want confirmation that Git staged the intended files, especially in scripts or larger repositories.
For example:
git add -v *.js
With -v, Git outputs each path it processes, so you can watch exactly what is being added in real time.
Force Add Ignored Files: --force
By default, Git does not stage files matching .gitignore or global ignore rules. Use the --force option to override that behavior. The feature is useful when you need to bring an otherwise-ignored file under version control temporarily (e.g., a sensitive config you only want to track for one commit).
For example:
git add --force secret-config.ymlAlthough the secret-config.yml file matches our ignore pattern, the --force option makes Git stage it. The index will now include that file, while subsequent commits will track it.
Interactively Select Changes: --interactive
The --interactive (-i) flag launches a menu-driven prompt that lets you selectively stage files or hunks. It is ideal when you have multiple edits and want to visually inspect and choose what to include in a commit.
The command is:
git add --interactiveThe output is a prompt as the one below:
Press 2 (update) to choose files or 5 (patch) to move to hunk selection. You can drill down into each file, stage exactly what you need, and then exit back to the shell with changes staged only as you specified.
Stage Specific Hunks: --patch
The --patch (-p) option allows users to walk through each diff hunk in the working tree and decide interactively whether to stage that hunk or not. Doing so skips the initial menu of --interactive and goes straight to the hunk-by-hunk selection, which is perfect for cherry-picking individual lines from large changes.
For example:
git add --patch script.js
Press y to stage a particular hunk, n to skip it, or e to manually edit the hunk before staging. The option provides precise control over what enters the next commit.
Edit the Patch Before Staging: --edit
Use the --edit (-e) option when you want to modify the diff itself before it goes into the index. The option is useful when you need to tweak a renamed variable or split a hunk differently. Git opens your $GIT_EDITOR on the patch, and whatever you save will be applied to the index.
For example:
git add --edit script.js
Git launches an editor showing the unified diff between script.js and the index. You can alter lines or remove them entirely. When you save and close the file, Git adjusts the staged changes to match your new patch.
Update Only Tracked Files: --update
The --update (-u) option stages modifications and deletions for files already under version control, but leaves untracked files untouched. It is especially useful when you remove or modify several tracked files and want to commit only those changes without bringing in any newly added files.
The command is:
git add --updateThe command scans your working tree for any tracked files with changes or deletions, then stages only those files. Git ignores newly added (untracked) files and updates only existing paths in the index.
Stage All Changes: --all
The --all (-A) option tells Git to update the index so that it mirrors the entire working tree. It adds new files, updates modified files, and records deletions. It is a quick way to stage everything before committing.
The command is:
git add --allAfter running the command, the index matches your working tree exactly, including removed files. Consequently, the next Git commit will capture every addition, modification, and deletion in one shot.
In comparison, if you want to stages all changes (including deletions in Git 2.0+) for files only under the current directory and its subdirectories, run the command below:
git add .Ignore File Deletions: --ignore-removal
If you want to add new and modified files but consciously skip deleting files (for example, if you are not ready to commit removals), use the --ignore-removal (--no-all) option. This option lets you avoid accidentally staging file deletions when you run git add.
For example:
git add --ignore-removal *.mdGit stages any new or edited Markdown (.md) files, but does not record deleted files in the index. It mimics older Git behavior where Git skips removals by default.
Signal Intent to Add: --intent-to-add
Use the --intent-to-add (-N) option to tell Git you plan to add a new file later, even though you have not actually placed content in the index yet. This option creates an empty index entry so that git diff can show you changes to that new file. It also reserves the path so a future commit can include it via -a.
For example:
git add --intent-to-add script.jsNow git diff will show all unstaged edits for the file, like in the example below:
When you are ready, perform a regular git add to stage the file's current contents for commit.
Conclusion
This article explained how to use git add to control precisely which changes each commit records. Use the options for a cleaner, more meaningful project history, to group related modifications, cherry-pick individual hunks, or batch everything in one go.
Next, learn to explore Git commit history or view file modifications line-by-line with git blame.
