Merge branch 'master' of ssh://Culex@repo.or.cz/srv/git/gitman-de
[gitman-de.git] / git-stash.txt
blob7d50d74cc9a945f0dd82b0c26509bf0392eff837
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
12 'git stash' (show | apply | drop | pop ) [<stash>]
13 'git stash' branch <branchname> [<stash>]
14 'git stash' [save [<message>]]
15 'git stash' clear
17 DESCRIPTION
18 -----------
20 Use 'git stash' when you want to record the current state of the
21 working directory and the index, but want to go back to a clean
22 working directory.  The command saves your local modifications away
23 and reverts the working directory to match the `HEAD` commit.
25 The modifications stashed away by this command can be listed with
26 `git stash list`, inspected with `git stash show`, and restored
27 (potentially on top of a different commit) with `git stash apply`.
28 Calling `git stash` without any arguments is equivalent to `git stash save`.
29 A stash is by default listed as "WIP on 'branchname' ...", but
30 you can give a more descriptive message on the command line when
31 you create one.
33 The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
34 stashes are found in the reflog of this reference and can be named using
35 the usual reflog syntax (e.g. `stash@\{0}` is the most recently
36 created stash, `stash@\{1}` is the one before it, `stash@\{2.hours.ago}`
37 is also possible).
39 OPTIONS
40 -------
42 save [--keep-index] [<message>]::
44         Save your local modifications to a new 'stash', and run `git reset
45         --hard` to revert them.  This is the default action when no
46         subcommand is given. The <message> part is optional and gives
47         the description along with the stashed state.
49 If the `--keep-index` option is used, all changes already added to the
50 index are left intact.
52 list [<options>]::
54         List the stashes that you currently have.  Each 'stash' is listed
55         with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is
56         the one before, etc.), the name of the branch that was current when the
57         stash was made, and a short description of the commit the stash was
58         based on.
60 ----------------------------------------------------------------
61 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
62 stash@{1}: On master: 9cc0589... Add git-stash
63 ----------------------------------------------------------------
65 The command takes options applicable to the 'git-log'
66 command to control what is shown and how. See linkgit:git-log[1].
68 show [<stash>]::
70         Show the changes recorded in the stash as a diff between the
71         stashed state and its original parent. When no `<stash>` is given,
72         shows the latest one. By default, the command shows the diffstat, but
73         it will accept any format known to 'git-diff' (e.g., `git stash show
74         -p stash@\{1}` to view the second most recent stash in patch form).
76 apply [--index] [<stash>]::
78         Restore the changes recorded in the stash on top of the current
79         working tree state.  When no `<stash>` is given, applies the latest
80         one.  The working directory must match the index.
82 This operation can fail with conflicts; you need to resolve them
83 by hand in the working tree.
85 If the `--index` option is used, then tries to reinstate not only the working
86 tree's changes, but also the index's ones. However, this can fail, when you
87 have conflicts (which are stored in the index, where you therefore can no
88 longer apply the changes as they were originally).
90 branch <branchname> [<stash>]::
92         Creates and checks out a new branch named `<branchname>` starting from
93         the commit at which the `<stash>` was originally created, applies the
94         changes recorded in `<stash>` to the new working tree and index, then
95         drops the `<stash>` if that completes successfully. When no `<stash>`
96         is given, applies the latest one.
98 This is useful if the branch on which you ran `git stash save` has
99 changed enough that `git stash apply` fails due to conflicts. Since
100 the stash is applied on top of the commit that was HEAD at the time
101 `git stash` was run, it restores the originally stashed state with
102 no conflicts.
104 clear::
105         Remove all the stashed states. Note that those states will then
106         be subject to pruning, and may be difficult or impossible to recover.
108 drop [<stash>]::
110         Remove a single stashed state from the stash list. When no `<stash>`
111         is given, it removes the latest one. i.e. `stash@\{0}`
113 pop [<stash>]::
115         Remove a single stashed state from the stash list and apply on top
116         of the current working tree state. When no `<stash>` is given,
117         `stash@\{0}` is assumed. See also `apply`.
120 DISCUSSION
121 ----------
123 A stash is represented as a commit whose tree records the state of the
124 working directory, and its first parent is the commit at `HEAD` when
125 the stash was created.  The tree of the second parent records the
126 state of the index when the stash is made, and it is made a child of
127 the `HEAD` commit.  The ancestry graph looks like this:
129             .----W
130            /    /
131      -----H----I
133 where `H` is the `HEAD` commit, `I` is a commit that records the state
134 of the index, and `W` is a commit that records the state of the working
135 tree.
138 EXAMPLES
139 --------
141 Pulling into a dirty tree::
143 When you are in the middle of something, you learn that there are
144 upstream changes that are possibly relevant to what you are
145 doing.  When your local changes do not conflict with the changes in
146 the upstream, a simple `git pull` will let you move forward.
148 However, there are cases in which your local changes do conflict with
149 the upstream changes, and `git pull` refuses to overwrite your
150 changes.  In such a case, you can stash your changes away,
151 perform a pull, and then unstash, like this:
153 ----------------------------------------------------------------
154 $ git pull
156 file foobar not up to date, cannot merge.
157 $ git stash
158 $ git pull
159 $ git stash apply
160 ----------------------------------------------------------------
162 Interrupted workflow::
164 When you are in the middle of something, your boss comes in and
165 demands that you fix something immediately.  Traditionally, you would
166 make a commit to a temporary branch to store your changes away, and
167 return to your original branch to make the emergency fix, like this:
169 ----------------------------------------------------------------
170 ... hack hack hack ...
171 $ git checkout -b my_wip
172 $ git commit -a -m "WIP"
173 $ git checkout master
174 $ edit emergency fix
175 $ git commit -a -m "Fix in a hurry"
176 $ git checkout my_wip
177 $ git reset --soft HEAD^
178 ... continue hacking ...
179 ----------------------------------------------------------------
181 You can use 'git-stash' to simplify the above, like this:
183 ----------------------------------------------------------------
184 ... hack hack hack ...
185 $ git stash
186 $ edit emergency fix
187 $ git commit -a -m "Fix in a hurry"
188 $ git stash apply
189 ... continue hacking ...
190 ----------------------------------------------------------------
192 Testing partial commits::
194 You can use `git stash save --keep-index` when you want to make two or
195 more commits out of the changes in the work tree, and you want to test
196 each change before committing:
198 ----------------------------------------------------------------
199 ... hack hack hack ...
200 $ git add --patch foo            # add just first part to the index
201 $ git stash save --keep-index    # save all other changes to the stash
202 $ edit/build/test first part
203 $ git commit foo -m 'First part' # commit fully tested change
204 $ git stash pop                  # prepare to work on all other changes
205 ... repeat above five steps until one commit remains ...
206 $ edit/build/test remaining parts
207 $ git commit foo -m 'Remaining parts'
208 ----------------------------------------------------------------
210 SEE ALSO
211 --------
212 linkgit:git-checkout[1],
213 linkgit:git-commit[1],
214 linkgit:git-reflog[1],
215 linkgit:git-reset[1]
217 AUTHOR
218 ------
219 Written by Nanako Shiraishi <nanako3@bluebottle.com>
223 Part of the linkgit:git[1] suite