git stash

What is the git stash command?

Git stash is a built-in command that stores, or stashes, changes in the software development tool Git that aren't yet ready to be committed. When a developer runs the git stash command, Git stores all the changes in a stash and resets the state of the workspace to its prior commit state.

Git stash acts as a version control tool and lets developers work on other activities or switch branches in Git without having to discard or commit changes that aren't ready. Developers can simply stash the changes in their working directory and index state, and work on them later.

Git program version control
Git stash is a built-in command in the open source Git version control system, a program used by developers to manage source code.

How does git stash work?

Git stash functions as a built-in command in the distributed version control tool Git. Developers can run the git stash command to save their changes in a stash stack. Stashable files include untracked files, newly added files and modified files. Git stash acts as a mechanism to locally store version files hidden from other developers who share the same git repository.

A developer can then retrieve all files put into the stash with the git stash pop and git stash apply commands, two commands similar to git stash. By default, the git stash command restores the most recent files, although developers can specify which stash they want applied.

Git stash also notifies developers if there's a merge conflict, which can occur when changes made to a branch conflict with stashed changes. Git stash asks developers to manually resolve the conflict. They can then commit their changes by applying the git commit command.

Git stash vs. commit

The git stash and git commit commands are similar in that both take a snapshot of modified files in the git working tree and store that snapshot for future reference. The following shows the key differences between the two commands:

  • A commit is part of the public git history; a stash is stored locally.
  • A commit creates a new save point on a branch; a stash reverts to a previous save point.
  • A new commit leaves files in the working tree unchanged; a stash resets files in the working tree to the previous commit point.
  • A commit is a public record of file changes; a stash is local.
Git commit command uses a unique identifier.
Git stash is often confused with git commit, a command that uses a unique identifier for easy rollback of changes.

Git stash vs. reset

The git stash and the git reset commands are similar, as both commands revert all files in the working directory back to the state at the point of the previous commit. Git reset is also often compared to the git revert command. Differences between the two include the following:

  • A reset creates a new commit point in the branch history. Stash doesn't.
  • A reset can jump back to any prior commit and undo previous local commits. A stash can only reset the files in the workspace to the point of the previous commit.
  • A hard reset discards all changes. A stash saves a snapshot of all locally modified files.

Git stash vs. stage

The git stash and git stage commands can be confused because of their similar names, but they're different. The git stage command simply adds work-in-progress files to the git index state WIP. This lets those files be part of a file system snapshot when a git commit occurs. This is a different construct compared to git stash, which simply stores uncommitted changes. However, git stage is required in the case of stashing untracked files.

Git stash commands

The most common git commands include the following:

  • git stash stashes all uncommitted files.
  • git stash save message allows a custom message to be added to a stash for identification.
  • git add stages ignored files so that the git stash command saves them.
  • git stash push creates a new stash, rolls back the state of all modified files and can stash untracked files in some cases.
  • git stash pop takes the files in a stash and places them back into the development workspace and deletes the stash from history.
  • git stash pop stash applies a specific stash to a workspace and deletes it from the stash stack.
  • git status shows developers the status of their repository.
  • git stash show lets developers inspect a summary of a stash.
Git show command coding graphic
The git show command highlights changes between file versions.
  • git stash show diff shows developers the difference between a stashed change and the current state of a repository.
  • git stash apply takes the files in a stash and places them back into the development workspace but doesn't delete the stash from history.
  • git stash apply stash restores only specific stashes without deleting them from the stash list.
  • git stash list displays the stash history of git branches in chronological order.
  • git stash branch <new_branch_name> creates a new branch from a specific stash.
  • git stash drop removes the most recent stash from the stash list.
  • git stash drop stash removes the most recent stash using a unique identifier.
  • git stash clear removes all stashes from the stash list.
  • git stash save is a command that's been deprecated in favor of git push.
Git stash commands image
Pop, apply and list are some of the most common git stash command options.

Which folder stores git stash history?

The latest git stash is stored in the hidden folder called a stash stack. The stash stack itself is located in the .git directory inside the /refs/stash file.

All other stashes are found in the reflog of this folder. This folder, which is different from a log, stores its contents in the order of the most recently used stash. Because this folder is hidden, developers can't view stashes using a simple file explorer. Instead they must use the git stash list command. When used, this command displays the stash list with each item's name, description and creation date.

Git stash best practices

Git developers should keep in mind the following best practices when using git stash:

  • Use unique identifiers. When creating a stash, developers should add a descriptive message that helps them identify their stash and recall why they made it. Messages can include why the stash is being stacked and what changes have been made.
  • Organize. Depending on how many stashes a developer keeps, stash stacks can become large and unwieldy. It's good practice to keep stash stacks organized by grouping similar stashes together, deleting old stashes and using clear naming tags.
  • Use temporarily. Git stash should only be used for small changes because it involves local repository history. Code stored in a local stash isn't visible to other developers, nor is it replicated to other git repositories such as GitHub or GitLab when a push occurs. Therefore, it's a better option to create development branches and commit regularly to these branches rather than a stash for larger changes. These branches replicate to other team members after a push, survive any local file system failures and make it easier for developers to review changes. Using stash makes the most sense when the changed files are small, shelved only temporarily and the intention is to come back within a short timeline.
  • Don't stash large changes. The size of stashed changes can make later application difficult because large changes can consume significant amounts of system resources while also increasing the likelihood of conflicts and merge issues. Therefore, large stashes should be broken up into smaller pieces that can be separately committed.

Examples of git stash uses

There are several popular use cases for git stash:

  • Saving work. If a developer is working on a new feature but has to suddenly switch to a new branch to fix a bug, their work can be saved using the git stash or git stash save message commands. These commands locally store and identify their stash. After working on the bug, a developer can switch back to their project by using the git checkout command followed by git stash apply to restore their work in progress.
  • Resolving conflicts. Developers can save local changes when they encounter merge conflicts by using the git stash command. Merge conflicts arise when there are incongruencies between changes from a remote branch and the workspace a developer is trying to apply them to. When this occurs, they can stash their local changes, resolve the conflict, merge the changes and apply their stashed changes on top of the merge.
  • Cleaning up a workspace. Git stash comes in handy when a workspace is cluttered with multiple changes that aren't ready to be committed. Git stash can stash specific changes so developers can focus on the changes that matter most.

Git stash is a built-in command in the software development tool Git. Learn the 5 ways to enable secure software development.

This was last updated in June 2023

Continue Reading About git stash

Dig Deeper on Software development best practices and processes

App Architecture
Software Quality
Cloud Computing