stash: introduce push verb
[git.git] / Documentation / git-stash.txt
blobd240df4af738164dd45114b3a3e3917fef6527e6
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 [<stash>]
13 'git stash' drop [-q|--quiet] [<stash>]
14 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
15 'git stash' branch <branchname> [<stash>]
16 'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
17              [-u|--include-untracked] [-a|--all] [<message>]]
18 'git stash' push [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
19              [-u|--include-untracked] [-a|--all] [-m|--message <message>]]
20 'git stash' clear
21 'git stash' create [<message>]
22 'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
24 DESCRIPTION
25 -----------
27 Use `git stash` when you want to record the current state of the
28 working directory and the index, but want to go back to a clean
29 working directory.  The command saves your local modifications away
30 and reverts the working directory to match the `HEAD` commit.
32 The modifications stashed away by this command can be listed with
33 `git stash list`, inspected with `git stash show`, and restored
34 (potentially on top of a different commit) with `git stash apply`.
35 Calling `git stash` without any arguments is equivalent to `git stash save`.
36 A stash is by default listed as "WIP on 'branchname' ...", but
37 you can give a more descriptive message on the command line when
38 you create one.
40 The latest stash you created is stored in `refs/stash`; older
41 stashes are found in the reflog of this reference and can be named using
42 the usual reflog syntax (e.g. `stash@{0}` is the most recently
43 created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
44 is also possible). Stashes may also be referenced by specifying just the
45 stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
47 OPTIONS
48 -------
50 save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
51 push [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [-m|--message <message>]::
53         Save your local modifications to a new 'stash' and roll them
54         back to HEAD (in the working tree and in the index).
55         The <message> part is optional and gives
56         the description along with the stashed state.  For quickly making
57         a snapshot, you can omit _both_ "save" and <message>, but giving
58         only <message> does not trigger this action to prevent a misspelled
59         subcommand from making an unwanted stash.
61 If the `--keep-index` option is used, all changes already added to the
62 index are left intact.
64 If the `--include-untracked` option is used, all untracked files are also
65 stashed and then cleaned up with `git clean`, leaving the working directory
66 in a very clean state. If the `--all` option is used instead then the
67 ignored files are stashed and cleaned in addition to the untracked files.
69 With `--patch`, you can interactively select hunks from the diff
70 between HEAD and the working tree to be stashed.  The stash entry is
71 constructed such that its index state is the same as the index state
72 of your repository, and its worktree contains only the changes you
73 selected interactively.  The selected changes are then rolled back
74 from your worktree. See the ``Interactive Mode'' section of
75 linkgit:git-add[1] to learn how to operate the `--patch` mode.
77 The `--patch` option implies `--keep-index`.  You can use
78 `--no-keep-index` to override this.
80 list [<options>]::
82         List the stashes that you currently have.  Each 'stash' is listed
83         with its name (e.g. `stash@{0}` is the latest stash, `stash@{1}` is
84         the one before, etc.), the name of the branch that was current when the
85         stash was made, and a short description of the commit the stash was
86         based on.
88 ----------------------------------------------------------------
89 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
90 stash@{1}: On master: 9cc0589... Add git-stash
91 ----------------------------------------------------------------
93 The command takes options applicable to the 'git log'
94 command to control what is shown and how. See linkgit:git-log[1].
96 show [<stash>]::
98         Show the changes recorded in the stash as a diff between the
99         stashed state and its original parent. When no `<stash>` is given,
100         shows the latest one. By default, the command shows the diffstat, but
101         it will accept any format known to 'git diff' (e.g., `git stash show
102         -p stash@{1}` to view the second most recent stash in patch form).
103         You can use stash.showStat and/or stash.showPatch config variables
104         to change the default behavior.
106 pop [--index] [-q|--quiet] [<stash>]::
108         Remove a single stashed state from the stash list and apply it
109         on top of the current working tree state, i.e., do the inverse
110         operation of `git stash save`. The working directory must
111         match the index.
113 Applying the state can fail with conflicts; in this case, it is not
114 removed from the stash list. You need to resolve the conflicts by hand
115 and call `git stash drop` manually afterwards.
117 If the `--index` option is used, then tries to reinstate not only the working
118 tree's changes, but also the index's ones. However, this can fail, when you
119 have conflicts (which are stored in the index, where you therefore can no
120 longer apply the changes as they were originally).
122 When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must
123 be a reference of the form `stash@{<revision>}`.
125 apply [--index] [-q|--quiet] [<stash>]::
127         Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
128         `<stash>` may be any commit that looks like a commit created by
129         `stash save` or `stash create`.
131 branch <branchname> [<stash>]::
133         Creates and checks out a new branch named `<branchname>` starting from
134         the commit at which the `<stash>` was originally created, applies the
135         changes recorded in `<stash>` to the new working tree and index.
136         If that succeeds, and `<stash>` is a reference of the form
137         `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>`
138         is given, applies the latest one.
140 This is useful if the branch on which you ran `git stash save` has
141 changed enough that `git stash apply` fails due to conflicts. Since
142 the stash is applied on top of the commit that was HEAD at the time
143 `git stash` was run, it restores the originally stashed state with
144 no conflicts.
146 clear::
147         Remove all the stashed states. Note that those states will then
148         be subject to pruning, and may be impossible to recover (see
149         'Examples' below for a possible strategy).
151 drop [-q|--quiet] [<stash>]::
153         Remove a single stashed state from the stash list. When no `<stash>`
154         is given, it removes the latest one. i.e. `stash@{0}`, otherwise
155         `<stash>` must be a valid stash log reference of the form
156         `stash@{<revision>}`.
158 create::
160         Create a stash (which is a regular commit object) and return its
161         object name, without storing it anywhere in the ref namespace.
162         This is intended to be useful for scripts.  It is probably not
163         the command you want to use; see "save" above.
165 store::
167         Store a given stash created via 'git stash create' (which is a
168         dangling merge commit) in the stash ref, updating the stash
169         reflog.  This is intended to be useful for scripts.  It is
170         probably not the command you want to use; see "save" above.
172 DISCUSSION
173 ----------
175 A stash is represented as a commit whose tree records the state of the
176 working directory, and its first parent is the commit at `HEAD` when
177 the stash was created.  The tree of the second parent records the
178 state of the index when the stash is made, and it is made a child of
179 the `HEAD` commit.  The ancestry graph looks like this:
181             .----W
182            /    /
183      -----H----I
185 where `H` is the `HEAD` commit, `I` is a commit that records the state
186 of the index, and `W` is a commit that records the state of the working
187 tree.
190 EXAMPLES
191 --------
193 Pulling into a dirty tree::
195 When you are in the middle of something, you learn that there are
196 upstream changes that are possibly relevant to what you are
197 doing.  When your local changes do not conflict with the changes in
198 the upstream, a simple `git pull` will let you move forward.
200 However, there are cases in which your local changes do conflict with
201 the upstream changes, and `git pull` refuses to overwrite your
202 changes.  In such a case, you can stash your changes away,
203 perform a pull, and then unstash, like this:
205 ----------------------------------------------------------------
206 $ git pull
207  ...
208 file foobar not up to date, cannot merge.
209 $ git stash
210 $ git pull
211 $ git stash pop
212 ----------------------------------------------------------------
214 Interrupted workflow::
216 When you are in the middle of something, your boss comes in and
217 demands that you fix something immediately.  Traditionally, you would
218 make a commit to a temporary branch to store your changes away, and
219 return to your original branch to make the emergency fix, like this:
221 ----------------------------------------------------------------
222 # ... hack hack hack ...
223 $ git checkout -b my_wip
224 $ git commit -a -m "WIP"
225 $ git checkout master
226 $ edit emergency fix
227 $ git commit -a -m "Fix in a hurry"
228 $ git checkout my_wip
229 $ git reset --soft HEAD^
230 # ... continue hacking ...
231 ----------------------------------------------------------------
233 You can use 'git stash' to simplify the above, like this:
235 ----------------------------------------------------------------
236 # ... hack hack hack ...
237 $ git stash
238 $ edit emergency fix
239 $ git commit -a -m "Fix in a hurry"
240 $ git stash pop
241 # ... continue hacking ...
242 ----------------------------------------------------------------
244 Testing partial commits::
246 You can use `git stash save --keep-index` when you want to make two or
247 more commits out of the changes in the work tree, and you want to test
248 each change before committing:
250 ----------------------------------------------------------------
251 # ... hack hack hack ...
252 $ git add --patch foo            # add just first part to the index
253 $ git stash save --keep-index    # save all other changes to the stash
254 $ edit/build/test first part
255 $ git commit -m 'First part'     # commit fully tested change
256 $ git stash pop                  # prepare to work on all other changes
257 # ... repeat above five steps until one commit remains ...
258 $ edit/build/test remaining parts
259 $ git commit foo -m 'Remaining parts'
260 ----------------------------------------------------------------
262 Recovering stashes that were cleared/dropped erroneously::
264 If you mistakenly drop or clear stashes, they cannot be recovered
265 through the normal safety mechanisms.  However, you can try the
266 following incantation to get a list of stashes that are still in your
267 repository, but not reachable any more:
269 ----------------------------------------------------------------
270 git fsck --unreachable |
271 grep commit | cut -d\  -f3 |
272 xargs git log --merges --no-walk --grep=WIP
273 ----------------------------------------------------------------
276 SEE ALSO
277 --------
278 linkgit:git-checkout[1],
279 linkgit:git-commit[1],
280 linkgit:git-reflog[1],
281 linkgit:git-reset[1]
285 Part of the linkgit:git[1] suite