Alex - stock.adobe.com
Inherently distributed in nature, every local commit made to a Git repo will make its way to the shared, central repository, as soon a developer issues a push command.
But this isn't always ideal. There are times when a developer creates a temporary file, performs an experimental update, or just wants to shelve temporary changes locally without the work becoming a permanent part of the distributed ledger. That's where git stash comes in.
In this git stash tutorial, we will demonstrate how developers can save changes to their working directory locally, just as they would with a git commit command. But instead of the commit being saved to a distributed development branch, the files are saved only in local storage. Developers can then bring stashed files back into the working tree at any point in the future.
How to perform a git stash
To perform a git stash, a developer would follow these steps:
- Add a new commit to the local repository.
- Add, update or delete files in the local workspace.
- Issue the git stash command.
- Continue to edit code in the local workspace.
- Call the git stash pop command to add the previously stashed files to the workspace.
Git stash command example
The following example shows the lifecycle of a git stash command, from the creation of an empty repository to the point where a stash is popped back on the workspace:
git init echo "Git stash tutorial." >> example.html git add . git commit -m "First git commit" echo "Updated git stash tutorial." >> example.html git stash rm example.html git commit -am "updated the file" git stash pop
In this git stash example, we initialize a new Git repository and add a file named example.html. The file is edited and then stashed. The user then deletes the file and adds a commit. When we later decide the file is necessary, we perform a git stash pop command, and the file is added back into the user's working directory.
Git stash pop vs. apply
There are two switches that can reapply a stash to the local workspace: pop and apply.
When you use git stash pop, the pulled stash is deleted. With the git stash apply command, the stash is added to the local workspace, but the stash itself is left intact.
Developers with an older version of Git may need to run the git stash save command instead of git stash push. The save switch still works on current versions, but it is deprecated, so the use of push is recommended.
The git stash list
Over time, the number of workspaces added to the stash can build up. To see a history, simply use the git stash list command:
git stash list
If the list is extensive, you can format the output with the same decorative options that are available to the git log command.
git stash list --after 7.days.ago git stash list --before 7.days.ago
To remove all the entries in the stash, you can use the clear switch:
git stash clear
Every Git repo has a .gitignore file that tells the tool not to add certain file types to the repository. However, sometimes a developer might want to add a scrapbook page or test file to the stash so they can come back to it later. To achieve this, use the --include-untracked switch:
git stash push --include-untracked
Merge conflicts with git stash
Developers typically associate conflicts with branch merges and the rebase command. However, if a developer has edited a stashed file, it's possible a pop or apply command could have resulted in a merge conflict.
If a conflict occurs, the developer will have an opportunity to edit the flagged file. After the consolidated file is saved, the developer will need to add the updated file to the index and perform a commit to bring the workspace back to a stable state.
Sometimes developers will have files they want to track locally or will shelve for later use without making that file part of the globally shared Git repository. In these situations, the git stash command is the ideal tool to use.