Skip to content

Basic cleanup of stash part of "Stashing and Cleaning" section #898

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 25, 2017
Merged

Basic cleanup of stash part of "Stashing and Cleaning" section #898

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 19 additions & 11 deletions book/07-git-tools/sections/stashing-cleaning.asc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,21 @@ Often, when you’ve been working on part of your project, things are in a messy
The problem is, you don’t want to do a commit of half-done work just so you can get back to this point later.
The answer to this issue is the `git stash` command.

Stashing takes the dirty state of your working directory – that is, your modified tracked files and staged changes – and saves it on a stack of unfinished changes that you can reapply at any time.
Stashing takes the dirty state of your working directory -- that is, your modified tracked files and staged changes -- and saves it on a stack of unfinished changes that you can reapply at any time (even on a different branch).

[NOTE]
.Migrating to `git stash push`
====
As of late October 2017, there has been extensive discussion on the Git mailing list, wherein the command `git stash save` is being deprecated in favour of the existing alternative `git stash push`.
The main reason for this is that `git stash push` introduces the option of stashing selected _pathspecs_, something `git stash save` does not support.

`git stash save` is not going away any time soon, so don't worry about it suddenly disappearing.
But you might want to start migrating over to the `push` alternative for the new functionality.
====

==== Stashing Your Work

To demonstrate, you’ll go into your project and start working on a couple of files and possibly stage one of the changes.
To demonstrate stashing, you’ll go into your project and start working on a couple of files and possibly stage one of the changes.
If you run `git status`, you can see your dirty state:

[source,console]
Expand Down Expand Up @@ -39,7 +49,7 @@ HEAD is now at 049d078 added the index file
(To restore them type "git stash apply")
----

Your working directory is clean:
You can now see that your working directory is clean:

[source,console]
----
Expand All @@ -48,7 +58,7 @@ $ git status
nothing to commit, working directory clean
----

At this point, you can easily switch branches and do work elsewhere; your changes are stored on your stack.
At this point, you can switch branches and do work elsewhere; your changes are stored on your stack.
To see which stashes you’ve stored, you can use `git stash list`:

[source,console]
Expand Down Expand Up @@ -82,7 +92,7 @@ You can see that Git re-modifies the files you reverted when you saved the stash
In this case, you had a clean working directory when you tried to apply the stash, and you tried to apply it on the same branch you saved it from.
Having a clean working directory and applying it on the same branch aren’t necessary to successfully apply a stash.
You can save a stash on one branch, switch to another branch later, and try to reapply the changes.
You can also have modified and uncommitted files in your working directory when you apply a stash – Git gives you merge conflicts if anything no longer applies cleanly.
You can also have modified and uncommitted files in your working directory when you apply a stash -- Git gives you merge conflicts if anything no longer applies cleanly.

The changes to your files were reapplied, but the file you staged before wasn’t restaged.
To do that, you must run the `git stash apply` command with a `--index` option to tell the command to try to reapply the staged changes.
Expand All @@ -104,7 +114,7 @@ Changes not staged for commit:
modified: lib/simplegit.rb
----

The apply option only tries to apply the stashed work – you continue to have it on your stack.
The apply option only tries to apply the stashed work -- you continue to have it on your stack.
To remove it, you can run `git stash drop` with the name of the stash to remove:

[source,console]
Expand All @@ -123,9 +133,7 @@ You can also run `git stash pop` to apply the stash and then immediately drop it

There are a few stash variants that may also be helpful.
The first option that is quite popular is the `--keep-index` option to the `stash save` command.
This tells Git to not stash anything that you've already staged with the `git add` command.

This can be really helpful if you've made a number of changes but want to only commit some of them and then come back to the rest of the changes at a later time.
This tells Git to not only include all staged content in the stash being created, but simultaneously leave it in the index.

[source,console]
----
Expand All @@ -142,8 +150,8 @@ M index.html
----

Another common thing you may want to do with stash is to stash the untracked files as well as the tracked ones.
By default, `git stash` will only store files that are already in the index.
If you specify `--include-untracked` or `-u`, Git will also stash any untracked files you have created.
By default, `git stash` will stash only modified and staged _tracked_ files.
If you specify `--include-untracked` or `-u`, Git will include untracked files in the stash being created.

[source,console]
----
Expand Down