git stash: document apply's --index switch
[git/git.git] / Documentation / git-stash.txt
CommitLineData
09ccdb63
NS
1git-stash(1)
2============
3
4NAME
5----
6git-stash - Stash the changes in a dirty working directory away
7
8SYNOPSIS
9--------
10[verse]
ec96e0f6
NS
11'git-stash' (list | show [<stash>] | apply [<stash>] | clear)
12'git-stash' [save] [message...]
09ccdb63
NS
13
14DESCRIPTION
15-----------
16
fcb10a96 17Use 'git-stash' when you want to record the current state of the
09ccdb63
NS
18working directory and the index, but want to go back to a clean
19working directory. The command saves your local modifications away
20and reverts the working directory to match the `HEAD` commit.
21
22The modifications stashed away by this command can be listed with
23`git-stash list`, inspected with `git-stash show`, and restored
9488e875 24(potentially on top of a different commit) with `git-stash apply`.
aaca4914 25Calling git-stash without any arguments is equivalent to `git-stash
ec96e0f6
NS
26save`. A stash is by default listed as "WIP on 'branchname' ...", but
27you can give a more descriptive message on the command line when
28you create one.
09ccdb63
NS
29
30The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
9488e875 31stashes are found in the reflog of this reference and can be named using
e2c6de1c
SH
32the usual reflog syntax (e.g. `stash@\{0}` is the most recently
33created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`
9488e875 34is also possible).
09ccdb63
NS
35
36OPTIONS
37-------
38
9488e875 39save::
09ccdb63
NS
40
41 Save your local modifications to a new 'stash', and run `git-reset
fcb10a96
JH
42 --hard` to revert them. This is the default action when no
43 subcommand is given.
09ccdb63
NS
44
45list::
46
47 List the stashes that you currently have. Each 'stash' is listed
36717575 48 with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is
9488e875 49 the one before, etc.), the name of the branch that was current when the
09ccdb63
NS
50 stash was made, and a short description of the commit the stash was
51 based on.
52+
53----------------------------------------------------------------
ec96e0f6
NS
54stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
55stash@{1}: On master: 9cc0589... Add git-stash
09ccdb63
NS
56----------------------------------------------------------------
57
58show [<stash>]::
59
9488e875
JH
60 Show the changes recorded in the stash as a diff between the the
61 stashed state and its original parent. When no `<stash>` is given,
62 shows the latest one. By default, the command shows the diffstat, but
63 it will accept any format known to `git-diff` (e.g., `git-stash show
e2c6de1c 64 -p stash@\{1}` to view the second most recent stash in patch form).
09ccdb63 65
0bdcac56 66apply [--index] [<stash>]::
09ccdb63 67
9488e875 68 Restore the changes recorded in the stash on top of the current
09ccdb63 69 working tree state. When no `<stash>` is given, applies the latest
9488e875
JH
70 one. The working directory must match the index.
71+
72This operation can fail with conflicts; you need to resolve them
73by hand in the working tree.
0bdcac56
MV
74+
75If the `--index` option is used, then tries to reinstate not only the working
76tree's changes, but also the index's ones. However, this can fail, when you
77have conflicts (which are stored in the index, where you therefore can no
78longer apply the changes as they were originally).
09ccdb63
NS
79
80clear::
9488e875
JH
81 Remove all the stashed states. Note that those states will then
82 be subject to pruning, and may be difficult or impossible to recover.
09ccdb63
NS
83
84
85DISCUSSION
86----------
87
88A stash is represented as a commit whose tree records the state of the
89working directory, and its first parent is the commit at `HEAD` when
90the stash was created. The tree of the second parent records the
91state of the index when the stash is made, and it is made a child of
92the `HEAD` commit. The ancestry graph looks like this:
93
94 .----W
95 / /
114fd812 96 -----H----I
09ccdb63
NS
97
98where `H` is the `HEAD` commit, `I` is a commit that records the state
99of the index, and `W` is a commit that records the state of the working
100tree.
101
102
103EXAMPLES
104--------
105
106Pulling into a dirty tree::
107
108When you are in the middle of something, you learn that there are
9488e875
JH
109upstream changes that are possibly relevant to what you are
110doing. When your local changes do not conflict with the changes in
09ccdb63
NS
111the upstream, a simple `git pull` will let you move forward.
112+
113However, there are cases in which your local changes do conflict with
114the upstream changes, and `git pull` refuses to overwrite your
9488e875 115changes. In such a case, you can stash your changes away,
09ccdb63
NS
116perform a pull, and then unstash, like this:
117+
118----------------------------------------------------------------
119$ git pull
120...
121file foobar not up to date, cannot merge.
122$ git stash
123$ git pull
124$ git stash apply
125----------------------------------------------------------------
126
127Interrupted workflow::
128
129When you are in the middle of something, your boss comes in and
9488e875 130demands that you fix something immediately. Traditionally, you would
09ccdb63 131make a commit to a temporary branch to store your changes away, and
9488e875 132return to your original branch to make the emergency fix, like this:
09ccdb63
NS
133+
134----------------------------------------------------------------
135... hack hack hack ...
136$ git checkout -b my_wip
137$ git commit -a -m "WIP"
138$ git checkout master
139$ edit emergency fix
140$ git commit -a -m "Fix in a hurry"
141$ git checkout my_wip
142$ git reset --soft HEAD^
143... continue hacking ...
144----------------------------------------------------------------
145+
146You can use `git-stash` to simplify the above, like this:
147+
148----------------------------------------------------------------
149... hack hack hack ...
150$ git stash
151$ edit emergency fix
152$ git commit -a -m "Fix in a hurry"
153$ git stash apply
154... continue hacking ...
155----------------------------------------------------------------
156
157SEE ALSO
158--------
159gitlink:git-checkout[1],
160gitlink:git-commit[1],
161gitlink:git-reflog[1],
162gitlink:git-reset[1]
163
164AUTHOR
165------
166Written by Nanako Shiraishi <nanako3@bluebottle.com>
167
168GIT
169---
170Part of the gitlink:git[7] suite