revision traversal: show full history with merge simplification

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index a4cbd0ce60e73b4e1ec9ffadfaeee132f7ea054b..7d50d74cc9a945f0dd82b0c26509bf0392eff837 100644 (file)
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -39,12 +39,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>]::
 
@@ -59,7 +62,7 @@ stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
 stash@{1}: On master: 9cc0589... Add git-stash
 ----------------------------------------------------------------
 +
-The command takes options applicable to the `git-log`
+The command takes options applicable to the 'git-log'
 command to control what is shown and how. See linkgit:git-log[1].
 
 show [<stash>]::
@@ -67,7 +70,7 @@ show [<stash>]::
        Show the changes recorded in the stash as a diff between the
        stashed state and its original parent. When no `<stash>` is given,
        shows the latest one. By default, the command shows the diffstat, but
-       it will accept any format known to `git-diff` (e.g., `git stash show
+       it will accept any format known to 'git-diff' (e.g., `git stash show
        -p stash@\{1}` to view the second most recent stash in patch form).
 
 apply [--index] [<stash>]::
@@ -175,7 +178,7 @@ $ git reset --soft HEAD^
 ... continue hacking ...
 ----------------------------------------------------------------
 +
-You can use `git-stash` to simplify the above, like this:
+You can use 'git-stash' to simplify the above, like this:
 +
 ----------------------------------------------------------------
 ... hack hack hack ...
@@ -186,6 +189,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],