Add git-replace to .gitignore
[git/dscho.git] / Documentation / git-stash.txt
blob1cc24cc47e3b9845c9d1006ee58faed1bc731c49
1 git-stash(1)
2 ============
4 NAME
5 ----
6 git-stash - Stash the changes in a dirty working directory away
8 SYNOPSIS
9 --------
10 [verse]
11 'git stash' list [<options>]
12 'git stash' (show | drop | pop ) [<stash>]
13 '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
19 DESCRIPTION
20 -----------
22 Use 'git stash' when you want to record the current state of the
23 working directory and the index, but want to go back to a clean
24 working directory.  The command saves your local modifications away
25 and reverts the working directory to match the `HEAD` commit.
27 The modifications stashed away by this command can be listed with
28 `git stash list`, inspected with `git stash show`, and restored
29 (potentially on top of a different commit) with `git stash apply`.
30 Calling `git stash` without any arguments is equivalent to `git stash save`.
31 A stash is by default listed as "WIP on 'branchname' ...", but
32 you can give a more descriptive message on the command line when
33 you create one.
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 the usual reflog syntax (e.g. `stash@\{0}` is the most recently
38 created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`
39 is also possible).
41 OPTIONS
42 -------
44 save [--keep-index] [<message>]::
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         subcommand is given. The <message> part is optional and gives
49         the description along with the stashed state.
51 If the `--keep-index` option is used, all changes already added to the
52 index are left intact.
54 list [<options>]::
56         List the stashes that you currently have.  Each 'stash' is listed
57         with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is
58         the one before, etc.), the name of the branch that was current when the
59         stash was made, and a short description of the commit the stash was
60         based on.
62 ----------------------------------------------------------------
63 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
64 stash@{1}: On master: 9cc0589... Add git-stash
65 ----------------------------------------------------------------
67 The command takes options applicable to the 'git-log'
68 command to control what is shown and how. See linkgit:git-log[1].
70 show [<stash>]::
72         Show the changes recorded in the stash as a diff between the
73         stashed state and its original parent. When no `<stash>` is given,
74         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 stash@\{1}` to view the second most recent stash in patch form).
78 pop [<stash>]::
80         Remove a single stashed state from the stash list and apply it
81         on top of the current working tree state, i.e., do the inverse
82         operation of `git stash save`. The working directory must
83         match the index.
85 Applying the state can fail with conflicts; in this case, it is not
86 removed from the stash list. You need to resolve the conflicts by hand
87 and call `git stash drop` manually afterwards.
89 When no `<stash>` is given, `stash@\{0}` is assumed. See also `apply`.
91 apply [--index] [<stash>]::
93         Like `pop`, but do not remove the state from the stash list.
95 If the `--index` option is used, then tries to reinstate not only the working
96 tree's changes, but also the index's ones. However, this can fail, when you
97 have conflicts (which are stored in the index, where you therefore can no
98 longer apply the changes as they were originally).
100 branch <branchname> [<stash>]::
102         Creates and checks out a new branch named `<branchname>` starting from
103         the commit at which the `<stash>` was originally created, applies the
104         changes recorded in `<stash>` to the new working tree and index, then
105         drops the `<stash>` if that completes successfully. When no `<stash>`
106         is given, applies the latest one.
108 This is useful if the branch on which you ran `git stash save` has
109 changed enough that `git stash apply` fails due to conflicts. Since
110 the stash is applied on top of the commit that was HEAD at the time
111 `git stash` was run, it restores the originally stashed state with
112 no conflicts.
114 clear::
115         Remove all the stashed states. Note that those states will then
116         be subject to pruning, and may be difficult or impossible to recover.
118 drop [<stash>]::
120         Remove a single stashed state from the stash list. When no `<stash>`
121         is given, it removes the latest one. i.e. `stash@\{0}`
123 create::
125         Create a stash (which is a regular commit object) and return its
126         object name, without storing it anywhere in the ref namespace.
129 DISCUSSION
130 ----------
132 A stash is represented as a commit whose tree records the state of the
133 working directory, and its first parent is the commit at `HEAD` when
134 the stash was created.  The tree of the second parent records the
135 state of the index when the stash is made, and it is made a child of
136 the `HEAD` commit.  The ancestry graph looks like this:
138             .----W
139            /    /
140      -----H----I
142 where `H` is the `HEAD` commit, `I` is a commit that records the state
143 of the index, and `W` is a commit that records the state of the working
144 tree.
147 EXAMPLES
148 --------
150 Pulling into a dirty tree::
152 When you are in the middle of something, you learn that there are
153 upstream changes that are possibly relevant to what you are
154 doing.  When your local changes do not conflict with the changes in
155 the upstream, a simple `git pull` will let you move forward.
157 However, there are cases in which your local changes do conflict with
158 the upstream changes, and `git pull` refuses to overwrite your
159 changes.  In such a case, you can stash your changes away,
160 perform a pull, and then unstash, like this:
162 ----------------------------------------------------------------
163 $ git pull
164  ...
165 file foobar not up to date, cannot merge.
166 $ git stash
167 $ git pull
168 $ git stash pop
169 ----------------------------------------------------------------
171 Interrupted workflow::
173 When you are in the middle of something, your boss comes in and
174 demands that you fix something immediately.  Traditionally, you would
175 make a commit to a temporary branch to store your changes away, and
176 return to your original branch to make the emergency fix, like this:
178 ----------------------------------------------------------------
179 # ... hack hack hack ...
180 $ git checkout -b my_wip
181 $ git commit -a -m "WIP"
182 $ git checkout master
183 $ edit emergency fix
184 $ git commit -a -m "Fix in a hurry"
185 $ git checkout my_wip
186 $ git reset --soft HEAD^
187 # ... continue hacking ...
188 ----------------------------------------------------------------
190 You can use 'git-stash' to simplify the above, like this:
192 ----------------------------------------------------------------
193 # ... hack hack hack ...
194 $ git stash
195 $ edit emergency fix
196 $ git commit -a -m "Fix in a hurry"
197 $ git stash pop
198 # ... continue hacking ...
199 ----------------------------------------------------------------
201 Testing partial commits::
203 You can use `git stash save --keep-index` when you want to make two or
204 more commits out of the changes in the work tree, and you want to test
205 each change before committing:
207 ----------------------------------------------------------------
208 # ... hack hack hack ...
209 $ git add --patch foo            # add just first part to the index
210 $ git stash save --keep-index    # save all other changes to the stash
211 $ edit/build/test first part
212 $ git commit -m 'First part'     # commit fully tested change
213 $ git stash pop                  # prepare to work on all other changes
214 # ... repeat above five steps until one commit remains ...
215 $ edit/build/test remaining parts
216 $ git commit foo -m 'Remaining parts'
217 ----------------------------------------------------------------
219 SEE ALSO
220 --------
221 linkgit:git-checkout[1],
222 linkgit:git-commit[1],
223 linkgit:git-reflog[1],
224 linkgit:git-reset[1]
226 AUTHOR
227 ------
228 Written by Nanako Shiraishi <nanako3@bluebottle.com>
232 Part of the linkgit:git[1] suite