Merge pull request #898 from rpjday/stashing_cleaning

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

Author: ben

book/07-git-tools/sections/stashing-cleaning.asc

@@ -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]
@@ -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]
 ----
@@ -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]
@@ -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.
@@ -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]
@@ -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]
 ----
@@ -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]
 ----