git-stash.txt 5.55 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)
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 47 48

list::

	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
----------------------------------------------------------------

show [<stash>]::

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

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

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

clear::
82 83
	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
84 85 86 87 88 89 90 91 92 93 94 95 96


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
97
     -----H----I
しらいしななこ's avatar
しらいしななこ committed
98 99 100 101 102 103 104 105 106 107 108 109

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
110 111
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
112 113 114 115
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
116
changes.  In such a case, you can stash your changes away,
しらいしななこ's avatar
しらいしななこ committed
117 118 119 120 121 122 123 124 125 126 127 128 129 130
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
131
demands that you fix something immediately.  Traditionally, you would
しらいしななこ's avatar
しらいしななこ committed
132
make a commit to a temporary branch to store your changes away, and
133
return to your original branch to make the emergency fix, like this:
しらいしななこ's avatar
しらいしななこ committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
+
----------------------------------------------------------------
... 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
--------
160 161 162 163
linkgit:git-checkout[1],
linkgit:git-commit[1],
linkgit:git-reflog[1],
linkgit:git-reset[1]
しらいしななこ's avatar
しらいしななこ committed
164 165 166 167 168 169 170

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

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