git-stash.txt 5.66 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
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 93 94 95 96 97 98 99


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

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

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

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