Merge 'build-in git-mktree'

* commit '633e3556ccbc': (5835 commits)
  build-in git-mktree
  allow -t abbreviation for --track in git branch
  gitweb: Remove function prototypes (cleanup)
  Documentation: cloning to empty directory is allowed
  Clarify kind of conflict in merge-one-file helper
  git config: clarify --add and --get-color
  archive-tar.c: squelch a type mismatch warning
  Start 1.6.4 development
  Start 1.6.3.1 maintenance series.
  GIT 1.6.3
  t4029: use sh instead of bash
  t4200: convert sed expression which operates on non-text file to perl
  t4200: remove two unnecessary lines
  t/annotate-tests.sh: avoid passing a non-newline terminated file to sed
  t4118: avoid sed invocation on file without terminating newline
  t4118: add missing '&&'
  t8005: use egrep when extended regular expressions are required
  git-clean doc: the command only affects paths under $(cwd)
  improve error message in config.c
  t4018-diff-funcname: add cpp xfuncname pattern to syntax test
  ...

1 files changed, 90 insertions, 25 deletions

diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 05f40cff6c..051f94d26f 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -8,22 +8,27 @@ git-stash - Stash the changes in a dirty working directory away
 SYNOPSIS
 --------
 [verse]
-'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
-'git-stash' [save] [message...]
+'git stash' list [<options>]
+'git stash' (show | drop | pop ) [<stash>]
+'git stash' apply [--index] [<stash>]
+'git stash' branch <branchname> [<stash>]
+'git stash' [save [--keep-index] [<message>]]
+'git stash' clear
+'git stash' create
 
 DESCRIPTION
 -----------
 
-Use 'git-stash' when you want to record the current state of the
+Use 'git stash' when you want to record the current state of the
 working directory and the index, but want to go back to a clean
 working directory.  The command saves your local modifications away
 and reverts the working directory to match the `HEAD` commit.
 
 The modifications stashed away by this command can be listed with
-`git-stash list`, inspected with `git-stash show`, and restored
-(potentially on top of a different commit) with `git-stash apply`.
-Calling git-stash without any arguments is equivalent to `git-stash
-save`.  A stash is by default listed as "WIP on 'branchname' ...", but
+`git stash list`, inspected with `git stash show`, and restored
+(potentially on top of a different commit) with `git stash apply`.
+Calling `git stash` without any arguments is equivalent to `git stash save`.
+A stash is by default listed as "WIP on 'branchname' ...", but
 you can give a more descriptive message on the command line when
 you create one.
 
@@ -36,13 +41,17 @@ is also possible).
 OPTIONS
 -------
 
-save::
+save [--keep-index] [<message>]::
 
-	Save your local modifications to a new 'stash', and run `git-reset
+	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.
+	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::
+list [<options>]::
 
 	List the stashes that you currently have.  Each 'stash' is listed
 	with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is
@@ -54,16 +63,19 @@ list::
 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'
+command to control what is shown and how. See linkgit:git-log[1].
 
 show [<stash>]::
 
-	Show the changes recorded in the stash as a diff between the the
+	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 [<stash>]::
+apply [--index] [<stash>]::
 
 	Restore the changes recorded in the stash on top of the current
 	working tree state.  When no `<stash>` is given, applies the latest
@@ -71,11 +83,46 @@ apply [<stash>]::
 +
 This operation can fail with conflicts; you need to resolve them
 by hand in the working tree.
++
+If the `--index` option is used, then tries to reinstate not only the working
+tree's changes, but also the index's ones. However, this can fail, when you
+have conflicts (which are stored in the index, where you therefore can no
+longer apply the changes as they were originally).
+
+branch <branchname> [<stash>]::
+
+	Creates and checks out a new branch named `<branchname>` starting from
+	the commit at which the `<stash>` was originally created, applies the
+	changes recorded in `<stash>` to the new working tree and index, then
+	drops the `<stash>` if that completes successfully. When no `<stash>`
+	is given, applies the latest one.
++
+This is useful if the branch on which you ran `git stash save` has
+changed enough that `git stash apply` fails due to conflicts. Since
+the stash is applied on top of the commit that was HEAD at the time
+`git stash` was run, it restores the originally stashed state with
+no conflicts.
 
 clear::
 	Remove all the stashed states. Note that those states will then
 	be subject to pruning, and may be difficult or impossible to recover.
 
+drop [<stash>]::
+
+	Remove a single stashed state from the stash list. When no `<stash>`
+	is given, it removes the latest one. i.e. `stash@\{0}`
+
+pop [<stash>]::
+
+	Remove a single stashed state from the stash list and apply on top
+	of the current working tree state. When no `<stash>` is given,
+	`stash@\{0}` is assumed. See also `apply`.
+
+create::
+
+	Create a stash (which is a regular commit object) and return its
+	object name, without storing it anywhere in the ref namespace.
+
 
 DISCUSSION
 ----------
@@ -112,7 +159,7 @@ perform a pull, and then unstash, like this:
 +
 ----------------------------------------------------------------
 $ git pull
-...
+ ...
 file foobar not up to date, cannot merge.
 $ git stash
 $ git pull
@@ -127,7 +174,7 @@ make a commit to a temporary branch to store your changes away, and
 return to your original branch to make the emergency fix, like this:
 +
 ----------------------------------------------------------------
-... hack hack hack ...
+# ... hack hack hack ...
 $ git checkout -b my_wip
 $ git commit -a -m "WIP"
 $ git checkout master
@@ -135,26 +182,44 @@ $ edit emergency fix
 $ git commit -a -m "Fix in a hurry"
 $ git checkout my_wip
 $ git reset --soft HEAD^
-... continue hacking ...
+# ... 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 ...
+# ... hack hack hack ...
 $ git stash
 $ edit emergency fix
 $ git commit -a -m "Fix in a hurry"
 $ git stash apply
-... continue hacking ...
+# ... 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 -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
 --------
-gitlink:git-checkout[1],
-gitlink:git-commit[1],
-gitlink:git-reflog[1],
-gitlink:git-reset[1]
+linkgit:git-checkout[1],
+linkgit:git-commit[1],
+linkgit:git-reflog[1],
+linkgit:git-reset[1]
 
 AUTHOR
 ------
@@ -162,4 +227,4 @@ Written by Nanako Shiraishi <nanako3@bluebottle.com>
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[1] suite