Stage Exact Files with git-stage, Then Check What Will Commit

By the end of this guide, you will have used git stage to put only the intended file contents into Git's index, checked the staged diff, and undone staging without losing work. 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 invoke it as a Git subcommand.

Allow about five minutes for a small change. You need a Git working tree with a file you are willing to edit. These commands do not need elevated privileges. Do not use sudo: it can create root-owned files and hide the repository you meant to change.

Checkpoint: inspect the working tree

1. Change to the repository and read its current status.

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

Git uses three useful states here. The working tree is what is on disk. The index, also called the staging area, is the snapshot prepared for the next commit. The last commit is HEAD. A line beginning with M has a modified file that is not staged. A line beginning with M has staged content, while ?? marks an untracked path.

If the status already contains changes you did not make, stop and identify them first. Staging is easy to undo, but committing someone else's work is harder to untangle.

Checkpoint: preview before changing the index

2. Ask Git what it would stage for named paths without changing anything.

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

The short form is git stage -n. This checks whether the paths exist and whether they would be ignored. A typical result names the paths that would be added. An ignored file produces a warning and is not staged by this command.

Use explicit paths when the change is small. The command accepts pathspecs, including directories and shell globs, but a broad path can include files you did not mean to prepare. If you use a glob that Git should expand recursively, quote it so the shell does not expand it first:

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

Review the output before moving on. The dry run is a check, not a preview of the complete patch. Use git diff for unstaged changes and git diff --cached for content already in the index.

Stage selected files

3. Stage the paths whose current contents belong in the next 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. Git does not add ignored files by default. Running the command again after editing a file is normal: each invocation stages the contents present at that moment.

Do not assume that staging freezes the file. It does not. If you edit src/config.yaml again, the index keeps the earlier version and the working tree contains the newer one. git status --short may then show both M and M on the same path.

Review exactly what the commit would contain

4. Compare the index with HEAD, then inspect the remaining unstaged work.

git diff --cached
git diff

git diff --cached is the important review before committing. It shows the staged patch, including new files. The plain git diff shows edits still only in the working tree. If the cached diff contains a secret, generated file, debug change, or unrelated hunk, do not commit yet.

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 that the boundary is correct.

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 really belongs in version control, force that one path explicitly:

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

This is a safety boundary, not a routine workaround. Before using --force, check the file's contents and why it is ignored. Never force-add a file containing passwords, private keys, tokens, or machine-specific secrets. Usually the better fix is to add a safe template to the repository and keep the real file ignored.

Undo staging without discarding edits

5. Remove a path from the index if the cached diff is wrong, 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 changes the index back towards HEAD; it does not restore 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.

Do not replace this command with git restore src/config.yaml unless you intend to discard the working-tree edits. That separate command can destroy uncommitted changes. If you are unsure, stop and save a copy of the file before using any restore operation.