Pause Work Safely with git stash

Someone needs you on another branch right now, and your tree is a mess: git stash tucks it away and hands it back later. You will finish with a named stash that clears a dirty working tree, a way to inspect it, and a safe method for restoring the work. The examples use Git 2.43.0 from the installed git-man package, version 1:2.43.0-1ubuntu7.3; the upstream manual records no changes to this command between 2.43.0 and 2.50.1, but newer releases may add options.

Allow about ten minutes. You need an existing Git repository with local changes that are not ready to commit. These are ordinary user commands: nothing here needs sudo, and elevated privileges can make ownership problems worse inside a working tree.

1. Check what would be stashed

Start in the repository and inspect the working tree. This does not change files or history:

$ cd /path/to/project
$ git --version
git version 2.43.0
$ git status --short
 M src/example.c
?? notes.txt

The first column describes the index, the second the working tree. Here src/example.c is modified and notes.txt is untracked. Treat this status output as the checkpoint before any state-changing command.

By default, git stash push saves tracked modifications in the index and working tree. It does not include untracked or ignored files unless you ask for them.

2. Create a named stash

Give the entry a short description, so it stays recognisable if several interruptions follow:

$ git stash push --message "pause parser experiment"
Saved working directory and index state On main: pause parser experiment

Running git stash without a subcommand is the same as git stash push, but the explicit form is easier to read back in scripts and shell history. Git records the working directory and index, then rolls those tracked changes back to HEAD. It does not create a commit on your current branch.

$ git status --short
$ git stash list
stash@{0}: On main: pause parser experiment

An empty tracked portion of the status does not mean every file disappeared: the untracked notes.txt remains, because the first command did not ask for untracked files.

3. Include untracked files only when you mean to

If the untracked files belong with the work in progress, make another stash with --include-untracked, or use that option in the original command next time:

$ git stash push --include-untracked --message "pause parser experiment with notes"
Saved working directory and index state On main: pause parser experiment with notes
$ git status --short
$ git stash list
stash@{0}: On main: pause parser experiment with notes
stash@{1}: On main: pause parser experiment

• --include-untracked also cleans included files. They are removed from the working tree once stashed, though ignored files are left alone.
• --all goes further. It includes ignored files too, then cleans them with git clean.

4. Inspect a stash before restoring it

Stashes are numbered from the newest entry, so stash@{0} is the latest and stash@{1} is the one before it. Inspect the summary first:

$ git stash show stash@{0}
 src/example.c | 4 +++-
 notes.txt     | 1 +
 2 files changed, 4 insertions(+), 1 deletion(-)

Use --patch when you need to read the actual diff. Add --include-untracked to the show command if the entry contains untracked files and you want them in the diff:

$ git stash show --patch --include-untracked stash@{0}

The exact paths and line counts depend on your work. If no stash name is supplied, Git uses the newest one.

5. Restore without deleting the safety copy

Use apply when you want to test the restoration while keeping the stash available:

$ git stash apply stash@{0}
On branch main
Changes not staged for commit:
  modified:   src/example.c
Untracked files:
  notes.txt

Check the result before doing more work:

$ git status --short
 M src/example.c
?? notes.txt
$ git diff --check

git diff --check reports whitespace errors in the resulting worktree and is a useful, read-only sanity check. If the restored files are wrong, discard only changes you have reviewed and can recreate. Restore the affected paths from your branch, or remove the newly created untracked files after checking them. Do not run a blanket cleanup command when you are unsure what is present.

If the original changes included staged work, try git stash apply --index stash@{0}. Git attempts to restore both the working tree and the index, but this can fail when conflicts occupy the index. Without --index, the file content is restored but the original staging state is not.

6. Remove the stash only after checking the result

Once the applied files are correct, remove the saved entry explicitly:

$ git stash drop stash@{0}
Dropped stash@{0} (a1b2c3d4e5f6...)

The identifier in the message varies. drop removes one entry. pop combines apply and drop, but it is less forgiving: if applying conflicts, Git leaves the stash in the list so you can resolve the conflict and drop it yourself. For important work, prefer apply, verify, then drop.

7. Handle conflicts or an accidental drop

A stash can be applied on top of a different commit. If the branch has changed enough, Git may report conflicts. The stash remains available after a failed pop. Resolve the conflict markers, stage the resolved files, and run your tests before dropping the stash:

$ git status
$ git add path/to/resolved-file
$ git diff --cached --check
$ git stash drop stash@{0}

If applying to the current branch is too difficult, git stash branch restore-parser stash@{0} creates and checks out a branch from the commit where the stash was made, then applies the changes there. If that succeeds for a normal stash@{n} reference, Git drops the stash entry.

$ git fsck --unreachable |
  grep commit |
  cut -d\  -f3 |
  xargs git log --merges --no-walk --grep=WIP

Recovery is not guaranteed, especially after pruning. A stash is a temporary Git object, not a replacement for a commit or a backup.