Merge branch 'tg/deprecate-stash-save'
[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]
a5ab00c5 11'git stash' list [<options>]
fcdd0e92
SB
12'git stash' show [<stash>]
13'git stash' drop [-q|--quiet] [<stash>]
14'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
656b5034 15'git stash' branch <branchname> [<stash>]
1ada5020 16'git stash' [push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
f5727e26 17 [-u|--include-untracked] [-a|--all] [-m|--message <message>]]
1ada5020 18 [--] [<pathspec>...]]
656b5034 19'git stash' clear
2be43516 20'git stash' create [<message>]
bd514cad 21'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
09ccdb63
NS
22
23DESCRIPTION
24-----------
25
ca768288 26Use `git stash` when you want to record the current state of the
09ccdb63
NS
27working directory and the index, but want to go back to a clean
28working directory. The command saves your local modifications away
29and reverts the working directory to match the `HEAD` commit.
30
31The modifications stashed away by this command can be listed with
483bc4f0
JN
32`git stash list`, inspected with `git stash show`, and restored
33(potentially on top of a different commit) with `git stash apply`.
db37745e 34Calling `git stash` without any arguments is equivalent to `git stash push`.
483bc4f0 35A stash is by default listed as "WIP on 'branchname' ...", but
ec96e0f6
NS
36you can give a more descriptive message on the command line when
37you create one.
09ccdb63 38
cc1b8d8b 39The latest stash you created is stored in `refs/stash`; older
9488e875 40stashes are found in the reflog of this reference and can be named using
6cf378f0
JK
41the usual reflog syntax (e.g. `stash@{0}` is the most recently
42created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
a56c8f5a
AW
43is also possible). Stashes may also be referenced by specifying just the
44stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
09ccdb63
NS
45
46OPTIONS
47-------
48
df6bba09 49push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>] [--] [<pathspec>...]::
09ccdb63 50
e01db917 51 Save your local modifications to a new 'stash entry' and roll them
20a7e061
TG
52 back to HEAD (in the working tree and in the index).
53 The <message> part is optional and gives
9e140909
TG
54 the description along with the stashed state.
55+
56For quickly making a snapshot, you can omit "push". In this mode,
57non-option arguments are not allowed to prevent a misspelled
e01db917 58subcommand from making an unwanted stash entry. The two exceptions to this
9e140909
TG
59are `stash -p` which acts as alias for `stash push -p` and pathspecs,
60which are allowed after a double hyphen `--` for disambiguation.
7bedebca 61+
e01db917 62When pathspec is given to 'git stash push', the new stash entry records the
df6bba09
TG
63modified states only for the files that match the pathspec. The index
64entries and working tree files are then rolled back to the state in
65HEAD only for these files, too, leaving files that do not match the
66pathspec intact.
67+
7bedebca
SG
68If the `--keep-index` option is used, all changes already added to the
69index are left intact.
dda1f2a5 70+
78751302
DC
71If the `--include-untracked` option is used, all untracked files are also
72stashed and then cleaned up with `git clean`, leaving the working directory
73in a very clean state. If the `--all` option is used instead then the
74ignored files are stashed and cleaned in addition to the untracked files.
75+
f2808a50 76With `--patch`, you can interactively select hunks from the diff
dda1f2a5
TR
77between HEAD and the working tree to be stashed. The stash entry is
78constructed such that its index state is the same as the index state
79of your repository, and its worktree contains only the changes you
80selected interactively. The selected changes are then rolled back
f2808a50 81from your worktree. See the ``Interactive Mode'' section of
6cf378f0 82linkgit:git-add[1] to learn how to operate the `--patch` mode.
dda1f2a5
TR
83+
84The `--patch` option implies `--keep-index`. You can use
85`--no-keep-index` to override this.
09ccdb63 86
fd2ebf14
TG
87save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
88
89 This option is deprecated in favour of 'git stash push'. It
90 differs from "stash push" in that it cannot take pathspecs,
91 and any non-option arguments form the message.
92
fbd538c2 93list [<options>]::
09ccdb63 94
e01db917
LB
95 List the stash entries that you currently have. Each 'stash entry' is
96 listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
9488e875 97 the one before, etc.), the name of the branch that was current when the
e01db917 98 entry was made, and a short description of the commit the entry was
09ccdb63
NS
99 based on.
100+
101----------------------------------------------------------------
ec96e0f6
NS
102stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
103stash@{1}: On master: 9cc0589... Add git-stash
09ccdb63 104----------------------------------------------------------------
fbd538c2 105+
0b444cdb 106The command takes options applicable to the 'git log'
b7b10385 107command to control what is shown and how. See linkgit:git-log[1].
09ccdb63
NS
108
109show [<stash>]::
110
e01db917
LB
111 Show the changes recorded in the stash entry as a diff between the
112 stashed contents and the commit back when the stash entry was first
113 created. When no `<stash>` is given, it shows the latest one.
114 By default, the command shows the diffstat, but it will accept any
115 format known to 'git diff' (e.g., `git stash show -p stash@{1}`
116 to view the second most recent entry in patch form).
3086c064
NK
117 You can use stash.showStat and/or stash.showPatch config variables
118 to change the default behavior.
09ccdb63 119
fcdd0e92 120pop [--index] [-q|--quiet] [<stash>]::
09ccdb63 121
d1836637
TR
122 Remove a single stashed state from the stash list and apply it
123 on top of the current working tree state, i.e., do the inverse
db37745e 124 operation of `git stash push`. The working directory must
d1836637 125 match the index.
9488e875 126+
d1836637
TR
127Applying the state can fail with conflicts; in this case, it is not
128removed from the stash list. You need to resolve the conflicts by hand
129and call `git stash drop` manually afterwards.
130+
0bdcac56
MV
131If the `--index` option is used, then tries to reinstate not only the working
132tree's changes, but also the index's ones. However, this can fail, when you
133have conflicts (which are stored in the index, where you therefore can no
134longer apply the changes as they were originally).
f39d6ee2 135+
6cf378f0
JK
136When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must
137be a reference of the form `stash@{<revision>}`.
f39d6ee2 138
fcdd0e92 139apply [--index] [-q|--quiet] [<stash>]::
f39d6ee2 140
b0c6bf4a
JS
141 Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
142 `<stash>` may be any commit that looks like a commit created by
db37745e 143 `stash push` or `stash create`.
09ccdb63 144
656b5034
AMS
145branch <branchname> [<stash>]::
146
147 Creates and checks out a new branch named `<branchname>` starting from
148 the commit at which the `<stash>` was originally created, applies the
b0c6bf4a
JS
149 changes recorded in `<stash>` to the new working tree and index.
150 If that succeeds, and `<stash>` is a reference of the form
151 `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>`
656b5034
AMS
152 is given, applies the latest one.
153+
db37745e 154This is useful if the branch on which you ran `git stash push` has
656b5034 155changed enough that `git stash apply` fails due to conflicts. Since
e01db917
LB
156the stash entry is applied on top of the commit that was HEAD at the
157time `git stash` was run, it restores the originally stashed state
158with no conflicts.
656b5034 159
09ccdb63 160clear::
e01db917 161 Remove all the stash entries. Note that those entries will then
f5f1e164
TR
162 be subject to pruning, and may be impossible to recover (see
163 'Examples' below for a possible strategy).
09ccdb63 164
fcdd0e92 165drop [-q|--quiet] [<stash>]::
e25d5f9c 166
e01db917
LB
167 Remove a single stash entry from the list of stash entries.
168 When no `<stash>` is given, it removes the latest one.
169 i.e. `stash@{0}`, otherwise `<stash>` must be a valid stash
170 log reference of the form `stash@{<revision>}`.
e25d5f9c 171
a5ab00c5
SB
172create::
173
e01db917
LB
174 Create a stash entry (which is a regular commit object) and
175 return its object name, without storing it anywhere in the ref
176 namespace.
2be43516 177 This is intended to be useful for scripts. It is probably not
0d5f844f 178 the command you want to use; see "push" above.
a5ab00c5 179
bd514cad
RR
180store::
181
182 Store a given stash created via 'git stash create' (which is a
183 dangling merge commit) in the stash ref, updating the stash
184 reflog. This is intended to be useful for scripts. It is
0d5f844f 185 probably not the command you want to use; see "push" above.
09ccdb63
NS
186
187DISCUSSION
188----------
189
e01db917
LB
190A stash entry is represented as a commit whose tree records the state
191of the working directory, and its first parent is the commit at `HEAD`
192when the entry was created. The tree of the second parent records the
193state of the index when the entry is made, and it is made a child of
09ccdb63
NS
194the `HEAD` commit. The ancestry graph looks like this:
195
196 .----W
197 / /
114fd812 198 -----H----I
09ccdb63
NS
199
200where `H` is the `HEAD` commit, `I` is a commit that records the state
201of the index, and `W` is a commit that records the state of the working
202tree.
203
204
205EXAMPLES
206--------
207
208Pulling into a dirty tree::
209
210When you are in the middle of something, you learn that there are
9488e875
JH
211upstream changes that are possibly relevant to what you are
212doing. When your local changes do not conflict with the changes in
09ccdb63
NS
213the upstream, a simple `git pull` will let you move forward.
214+
215However, there are cases in which your local changes do conflict with
216the upstream changes, and `git pull` refuses to overwrite your
9488e875 217changes. In such a case, you can stash your changes away,
09ccdb63
NS
218perform a pull, and then unstash, like this:
219+
220----------------------------------------------------------------
221$ git pull
9da6f0ff 222 ...
09ccdb63
NS
223file foobar not up to date, cannot merge.
224$ git stash
225$ git pull
d1836637 226$ git stash pop
09ccdb63
NS
227----------------------------------------------------------------
228
229Interrupted workflow::
230
231When you are in the middle of something, your boss comes in and
9488e875 232demands that you fix something immediately. Traditionally, you would
09ccdb63 233make a commit to a temporary branch to store your changes away, and
9488e875 234return to your original branch to make the emergency fix, like this:
09ccdb63
NS
235+
236----------------------------------------------------------------
9da6f0ff 237# ... hack hack hack ...
09ccdb63
NS
238$ git checkout -b my_wip
239$ git commit -a -m "WIP"
240$ git checkout master
241$ edit emergency fix
242$ git commit -a -m "Fix in a hurry"
243$ git checkout my_wip
244$ git reset --soft HEAD^
9da6f0ff 245# ... continue hacking ...
09ccdb63
NS
246----------------------------------------------------------------
247+
0b444cdb 248You can use 'git stash' to simplify the above, like this:
09ccdb63
NS
249+
250----------------------------------------------------------------
9da6f0ff 251# ... hack hack hack ...
09ccdb63
NS
252$ git stash
253$ edit emergency fix
254$ git commit -a -m "Fix in a hurry"
d1836637 255$ git stash pop
9da6f0ff 256# ... continue hacking ...
09ccdb63
NS
257----------------------------------------------------------------
258
7bedebca
SG
259Testing partial commits::
260
db37745e 261You can use `git stash push --keep-index` when you want to make two or
7bedebca
SG
262more commits out of the changes in the work tree, and you want to test
263each change before committing:
264+
265----------------------------------------------------------------
9da6f0ff 266# ... hack hack hack ...
caf18996 267$ git add --patch foo # add just first part to the index
db37745e 268$ git stash push --keep-index # save all other changes to the stash
caf18996 269$ edit/build/test first part
f733c709 270$ git commit -m 'First part' # commit fully tested change
caf18996 271$ git stash pop # prepare to work on all other changes
9da6f0ff 272# ... repeat above five steps until one commit remains ...
caf18996
ER
273$ edit/build/test remaining parts
274$ git commit foo -m 'Remaining parts'
7bedebca
SG
275----------------------------------------------------------------
276
e01db917 277Recovering stash entries that were cleared/dropped erroneously::
f5f1e164 278
e01db917 279If you mistakenly drop or clear stash entries, they cannot be recovered
f5f1e164 280through the normal safety mechanisms. However, you can try the
e01db917
LB
281following incantation to get a list of stash entries that are still in
282your repository, but not reachable any more:
f5f1e164
TR
283+
284----------------------------------------------------------------
285git fsck --unreachable |
286grep commit | cut -d\ -f3 |
287xargs git log --merges --no-walk --grep=WIP
288----------------------------------------------------------------
289
290
09ccdb63
NS
291SEE ALSO
292--------
5162e697
DM
293linkgit:git-checkout[1],
294linkgit:git-commit[1],
295linkgit:git-reflog[1],
296linkgit:git-reset[1]
09ccdb63 297
09ccdb63
NS
298GIT
299---
9e1f0a85 300Part of the linkgit:git[1] suite