git-stash.txt 7.8 KB
Newer Older
しらいしななこ's avatar
しらいしななこ committed
1 2 3 4 5 6 7 8 9 10
git-stash(1)
============

NAME
----
git-stash - Stash the changes in a dirty working directory away

SYNOPSIS
--------
[verse]
11 12 13
'git stash' list [<options>]
'git stash' (show | drop | pop ) [<stash>]
'git stash' apply [--index] [<stash>]
14
'git stash' branch <branchname> [<stash>]
15
'git stash' [save [--keep-index] [<message>]]
16
'git stash' clear
17
'git stash' create
しらいしななこ's avatar
しらいしななこ committed
18 19 20 21

DESCRIPTION
-----------

22
Use 'git stash' when you want to record the current state of the
しらいしななこ's avatar
しらいしななこ committed
23 24 25 26 27
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
28 29 30 31
`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
32 33
you can give a more descriptive message on the command line when
you create one.
しらいしななこ's avatar
しらいしななこ committed
34 35

The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
36
stashes are found in the reflog of this reference and can be named using
37 38
the usual reflog syntax (e.g. `[email protected]\{0}` is the most recently
created stash, `[email protected]\{1}` is the one before it, `[email protected]\{2.hours.ago}`
39
is also possible).
しらいしななこ's avatar
しらいしななこ committed
40 41 42 43

OPTIONS
-------

44
save [--keep-index] [<message>]::
しらいしななこ's avatar
しらいしななこ committed
45

46
	Save your local modifications to a new 'stash', and run `git reset
47
	--hard` to revert them.  This is the default action when no
48 49
	subcommand is given. The <message> part is optional and gives
	the description along with the stashed state.
50 51 52
+
If the `--keep-index` option is used, all changes already added to the
index are left intact.
しらいしななこ's avatar
しらいしななこ committed
53

54
list [<options>]::
しらいしななこ's avatar
しらいしななこ committed
55 56

	List the stashes that you currently have.  Each 'stash' is listed
57
	with its name (e.g. `[email protected]\{0}` is the latest stash, `[email protected]\{1}` is
58
	the one before, etc.), the name of the branch that was current when the
しらいしななこ's avatar
しらいしななこ committed
59 60 61 62
	stash was made, and a short description of the commit the stash was
	based on.
+
----------------------------------------------------------------
63 64
[email protected]{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
[email protected]{1}: On master: 9cc0589... Add git-stash
しらいしななこ's avatar
しらいしななこ committed
65
----------------------------------------------------------------
66
+
67
The command takes options applicable to the 'git-log'
68
command to control what is shown and how. See linkgit:git-log[1].
しらいしななこ's avatar
しらいしななこ committed
69 70 71

show [<stash>]::

72
	Show the changes recorded in the stash as a diff between the
73 74
	stashed state and its original parent. When no `<stash>` is given,
	shows the latest one. By default, the command shows the diffstat, but
75
	it will accept any format known to 'git-diff' (e.g., `git stash show
76
	-p [email protected]\{1}` to view the second most recent stash in patch form).
しらいしななこ's avatar
しらいしななこ committed
77

78
apply [--index] [<stash>]::
しらいしななこ's avatar
しらいしななこ committed
79

80
	Restore the changes recorded in the stash on top of the current
しらいしななこ's avatar
しらいしななこ committed
81
	working tree state.  When no `<stash>` is given, applies the latest
82 83 84 85
	one.  The working directory must match the index.
+
This operation can fail with conflicts; you need to resolve them
by hand in the working tree.
86 87 88 89 90
+
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).
しらいしななこ's avatar
しらいしななこ committed
91

92 93 94 95 96 97 98 99 100 101 102 103 104 105
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.

しらいしななこ's avatar
しらいしななこ committed
106
clear::
107 108
	Remove all the stashed states. Note that those states will then
	be subject to pruning, and may be difficult or impossible to recover.
しらいしななこ's avatar
しらいしななこ committed
109

110 111 112 113 114
drop [<stash>]::

	Remove a single stashed state from the stash list. When no `<stash>`
	is given, it removes the latest one. i.e. `[email protected]\{0}`

115 116 117 118 119 120
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,
	`[email protected]\{0}` is assumed. See also `apply`.

121 122 123 124 125
create::

	Create a stash (which is a regular commit object) and return its
	object name, without storing it anywhere in the ref namespace.

しらいしななこ's avatar
しらいしななこ committed
126 127 128 129 130 131 132 133 134 135 136 137

DISCUSSION
----------

A stash is represented as a commit whose tree records the state of the
working directory, and its first parent is the commit at `HEAD` when
the stash was created.  The tree of the second parent records the
state of the index when the stash is made, and it is made a child of
the `HEAD` commit.  The ancestry graph looks like this:

            .----W
           /    /
Junio C Hamano's avatar
Junio C Hamano committed
138
     -----H----I
しらいしななこ's avatar
しらいしななこ committed
139 140 141 142 143 144 145 146 147 148 149 150

where `H` is the `HEAD` commit, `I` is a commit that records the state
of the index, and `W` is a commit that records the state of the working
tree.


EXAMPLES
--------

Pulling into a dirty tree::

When you are in the middle of something, you learn that there are
151 152
upstream changes that are possibly relevant to what you are
doing.  When your local changes do not conflict with the changes in
しらいしななこ's avatar
しらいしななこ committed
153 154 155 156
the upstream, a simple `git pull` will let you move forward.
+
However, there are cases in which your local changes do conflict with
the upstream changes, and `git pull` refuses to overwrite your
157
changes.  In such a case, you can stash your changes away,
しらいしななこ's avatar
しらいしななこ committed
158 159 160 161
perform a pull, and then unstash, like this:
+
----------------------------------------------------------------
$ git pull
162
 ...
しらいしななこ's avatar
しらいしななこ committed
163 164 165 166 167 168 169 170 171
file foobar not up to date, cannot merge.
$ git stash
$ git pull
$ git stash apply
----------------------------------------------------------------

Interrupted workflow::

When you are in the middle of something, your boss comes in and
172
demands that you fix something immediately.  Traditionally, you would
しらいしななこ's avatar
しらいしななこ committed
173
make a commit to a temporary branch to store your changes away, and
174
return to your original branch to make the emergency fix, like this:
しらいしななこ's avatar
しらいしななこ committed
175 176
+
----------------------------------------------------------------
177
# ... hack hack hack ...
しらいしななこ's avatar
しらいしななこ committed
178 179 180 181 182 183 184
$ git checkout -b my_wip
$ git commit -a -m "WIP"
$ git checkout master
$ edit emergency fix
$ git commit -a -m "Fix in a hurry"
$ git checkout my_wip
$ git reset --soft HEAD^
185
# ... continue hacking ...
しらいしななこ's avatar
しらいしななこ committed
186 187
----------------------------------------------------------------
+
188
You can use 'git-stash' to simplify the above, like this:
しらいしななこ's avatar
しらいしななこ committed
189 190
+
----------------------------------------------------------------
191
# ... hack hack hack ...
しらいしななこ's avatar
しらいしななこ committed
192 193 194 195
$ git stash
$ edit emergency fix
$ git commit -a -m "Fix in a hurry"
$ git stash apply
196
# ... continue hacking ...
しらいしななこ's avatar
しらいしななこ committed
197 198
----------------------------------------------------------------

199 200 201 202 203 204 205
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:
+
----------------------------------------------------------------
206
# ... hack hack hack ...
207 208 209 210 211
$ 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
212
# ... repeat above five steps until one commit remains ...
213 214
$ edit/build/test remaining parts
$ git commit foo -m 'Remaining parts'
215 216
----------------------------------------------------------------

しらいしななこ's avatar
しらいしななこ committed
217 218
SEE ALSO
--------
219 220 221 222
linkgit:git-checkout[1],
linkgit:git-commit[1],
linkgit:git-reflog[1],
linkgit:git-reset[1]
しらいしななこ's avatar
しらいしななこ committed
223 224 225 226 227 228 229

AUTHOR
------
Written by Nanako Shiraishi <[email protected]>

GIT
---
230
Part of the linkgit:git[1] suite