git-stash.txt 6.03 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
'git-stash' (list | show [<stash>] | apply [<stash>] | clear | drop [<stash>] | pop [<stash>])
12
'git-stash' [save [<message>]]
しらいしななこ's avatar
しらいしななこ committed
13 14 15 16

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

17
Use 'git-stash' when you want to record the current state of the
しらいしななこ's avatar
しらいしななこ committed
18 19 20 21 22 23
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
24
(potentially on top of a different commit) with `git-stash apply`.
25
Calling git-stash without any arguments is equivalent to `git-stash
26 27 28
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.
しらいしななこ's avatar
しらいしななこ committed
29 30

The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
31
stashes are found in the reflog of this reference and can be named using
32 33
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}`
34
is also possible).
しらいしななこ's avatar
しらいしななこ committed
35 36 37 38

OPTIONS
-------

39
save [<message>]::
しらいしななこ's avatar
しらいしななこ committed
40 41

	Save your local modifications to a new 'stash', and run `git-reset
42
	--hard` to revert them.  This is the default action when no
43 44
	subcommand is given. The <message> part is optional and gives
	the description along with the stashed state.
しらいしななこ's avatar
しらいしななこ committed
45

46
list [<options>]::
しらいしななこ's avatar
しらいしななこ committed
47 48

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

show [<stash>]::

64
	Show the changes recorded in the stash as a diff between the
65 66 67
	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
68
	-p [email protected]\{1}` to view the second most recent stash in patch form).
しらいしななこ's avatar
しらいしななこ committed
69

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

72
	Restore the changes recorded in the stash on top of the current
しらいしななこ's avatar
しらいしななこ committed
73
	working tree state.  When no `<stash>` is given, applies the latest
74 75 76 77
	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.
78 79 80 81 82
+
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
83 84

clear::
85 86
	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
87

88 89 90 91 92
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}`

93 94 95 96 97 98
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`.

しらいしななこ's avatar
しらいしななこ committed
99 100 101 102 103 104 105 106 107 108 109 110

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
111
     -----H----I
しらいしななこ's avatar
しらいしななこ committed
112 113 114 115 116 117 118 119 120 121 122 123

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
124 125
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
126 127 128 129
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
130
changes.  In such a case, you can stash your changes away,
しらいしななこ's avatar
しらいしななこ committed
131 132 133 134 135 136 137 138 139 140 141 142 143 144
perform a pull, and then unstash, like this:
+
----------------------------------------------------------------
$ git pull
...
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
145
demands that you fix something immediately.  Traditionally, you would
しらいしななこ's avatar
しらいしななこ committed
146
make a commit to a temporary branch to store your changes away, and
147
return to your original branch to make the emergency fix, like this:
しらいしななこ's avatar
しらいしななこ committed
148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173
+
----------------------------------------------------------------
... hack hack hack ...
$ 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^
... continue hacking ...
----------------------------------------------------------------
+
You can use `git-stash` to simplify the above, like this:
+
----------------------------------------------------------------
... hack hack hack ...
$ git stash
$ edit emergency fix
$ git commit -a -m "Fix in a hurry"
$ git stash apply
... continue hacking ...
----------------------------------------------------------------

SEE ALSO
--------
174 175 176 177
linkgit:git-checkout[1],
linkgit:git-commit[1],
linkgit:git-reflog[1],
linkgit:git-reset[1]
しらいしななこ's avatar
しらいしななこ committed
178 179 180 181 182 183 184

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

GIT
---
185
Part of the linkgit:git[7] suite