Stage Files Precisely with git stage

You are about to commit and want the index to hold exactly the lines you meant, which is what git stage is for. The installed Git 2.43.0 documents git-stage(1) as a synonym for git-add(1): there is no separate git-stage executable, so you always invoke it as a Git subcommand. By the end you will have staged specific files, previewed the result before committing, and undone a bad stage without losing the edit.

Allow about five minutes for a small change. You need a Git working tree with a file you are willing to edit. No step here needs elevated privileges.

• No sudo. It can create root-owned files and hide the repository you meant to change.

1. Look at the working tree before you touch anything

Change to the repository and read its current status:

cd /path/to/project
git status --short

Git is comparing three things here: the working tree (what is on disk), the index (the snapshot prepared for the next commit, also called the staging area), and the last commit, HEAD. Read the two-character prefix carefully:

• M (leading space). Modified, not staged.
• M (trailing space). Staged content, ready to commit.
• ??. Untracked path.

2. Preview what would be staged, without staging it

Ask Git what it would do for named paths, with nothing actually changed:

git stage --dry-run src/config.yaml docs/deploy.md

• Short form. git stage -n does the same thing.
• What it checks. Whether the paths exist and whether they would be ignored; a typical result names the paths that would be added, and an ignored file gets a warning instead of being staged.
• Prefer explicit paths for a small change. The command accepts pathspecs, including directories and shell globs, but a broad path can sweep up files you never meant to prepare.

Quote a glob you want Git to expand recursively, so the shell does not expand it first:

git stage --dry-run 'docs/*.md'

A dry run is a check, not a preview of the complete patch. For that, use git diff for unstaged changes and git diff --cached for content already in the index.

3. Stage the files you actually mean to commit

git stage src/config.yaml docs/deploy.md
git status --short

For an existing tracked file, Git copies its current contents into the index. For a new file, it records the file for addition. Ignored files are not added by default. Running the command again after editing a file is completely normal: each invocation stages whatever is present at that moment.

4. Review exactly what the commit would contain

git diff --cached
git diff

git diff --cached is the review that matters before committing: it shows the staged patch, including new files. Plain git diff shows edits still only in the working tree.

To stage only part of a modified file, use patch mode. Git presents each hunk and lets you accept or reject it:

git stage --patch src/app.conf

Read each hunk rather than accepting the whole file on autopilot. Patch mode changes the index, not the working file. When it finishes, run git diff --cached again and confirm the boundary is right.

5. Handle ignored files deliberately

Ignored files are excluded by default, which protects build output, local settings, logs and credentials from accidental commits. If a particular ignored file genuinely belongs in version control, force that one path explicitly:

git stage --force path/to/example.log

6. Undo staging without discarding the edit

If the cached diff is wrong, remove a path from the index while keeping its working-tree changes:

git restore --staged src/config.yaml
git status --short

This is the usual recovery after staging too much. It moves the index back towards HEAD; it does not touch the file on disk. The path should return to an unstaged state, shown as M for a tracked modification. Review it again, or stage a smaller patch next time.