Merge branch 'sg/stash-k-i'

* sg/stash-k-i:
  Documentation: tweak use case in "git stash save --keep-index"
  stash: introduce 'stash save --keep-index' option

1 files changed, 22 insertions, 1 deletions

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 9b6b911091..e42c5eff4d 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -36,12 +36,15 @@ is also possible).
 OPTIONS
 -------
 
-save [<message>]::
+save [--keep-index] [<message>]::
 
 	Save your local modifications to a new 'stash', and run `git reset
 	--hard` to revert them.  This is the default action when no
 	subcommand is given. The <message> part is optional and gives
 	the description along with the stashed state.
++
+If the `--keep-index` option is used, all changes already added to the
+index are left intact.
 
 list [<options>]::
 
@@ -169,6 +172,24 @@ $ git stash apply
 ... continue hacking ...
 ----------------------------------------------------------------
 
+Testing partial commits::
+
+You can use `git stash save --keep-index` when you want to make two or
+more commits out of the changes in the work tree, and you want to test
+each change before committing:
++
+----------------------------------------------------------------
+... hack hack hack ...
+$ git add --patch foo            # add just first part to the index
+$ git stash save --keep-index    # save all other changes to the stash
+$ edit/build/test first part
+$ git commit foo -m 'First part' # commit fully tested change
+$ git stash pop                  # prepare to work on all other changes
+... repeat above five steps until one commit remains ...
+$ edit/build/test remaining parts
+$ git commit foo -m 'Remaining parts'
+----------------------------------------------------------------
+
 SEE ALSO
 --------
 linkgit:git-checkout[1],