Merge branch 'rs/midx-use-strvec-pushf'
[alt-git.git] / Documentation / git-stash.txt
blob06fb7f1d18c6bec047b9cbdb2487f72614fa6073
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 [<log-options>]
12 'git stash' show [-u | --include-untracked | --only-untracked] [<diff-options>] [<stash>]
13 'git stash' drop [-q | --quiet] [<stash>]
14 'git stash' pop [--index] [-q | --quiet] [<stash>]
15 'git stash' apply [--index] [-q | --quiet] [<stash>]
16 'git stash' branch <branchname> [<stash>]
17 'git stash' [push [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
18              [-u | --include-untracked] [-a | --all] [(-m | --message) <message>]
19              [--pathspec-from-file=<file> [--pathspec-file-nul]]
20              [--] [<pathspec>...]]
21 'git stash' save [-p | --patch] [-S | --staged] [-k | --[no-]keep-index] [-q | --quiet]
22              [-u | --include-untracked] [-a | --all] [<message>]
23 'git stash' clear
24 'git stash' create [<message>]
25 'git stash' store [(-m | --message) <message>] [-q | --quiet] <commit>
27 DESCRIPTION
28 -----------
30 Use `git stash` when you want to record the current state of the
31 working directory and the index, but want to go back to a clean
32 working directory.  The command saves your local modifications away
33 and reverts the working directory to match the `HEAD` commit.
35 The modifications stashed away by this command can be listed with
36 `git stash list`, inspected with `git stash show`, and restored
37 (potentially on top of a different commit) with `git stash apply`.
38 Calling `git stash` without any arguments is equivalent to `git stash push`.
39 A stash is by default listed as "WIP on 'branchname' ...", but
40 you can give a more descriptive message on the command line when
41 you create one.
43 The latest stash you created is stored in `refs/stash`; older
44 stashes are found in the reflog of this reference and can be named using
45 the usual reflog syntax (e.g. `stash@{0}` is the most recently
46 created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
47 is also possible). Stashes may also be referenced by specifying just the
48 stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
50 COMMANDS
51 --------
53 push [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [(-m|--message) <message>] [--pathspec-from-file=<file> [--pathspec-file-nul]] [--] [<pathspec>...]::
55         Save your local modifications to a new 'stash entry' and roll them
56         back to HEAD (in the working tree and in the index).
57         The <message> part is optional and gives
58         the description along with the stashed state.
60 For quickly making a snapshot, you can omit "push".  In this mode,
61 non-option arguments are not allowed to prevent a misspelled
62 subcommand from making an unwanted stash entry.  The two exceptions to this
63 are `stash -p` which acts as alias for `stash push -p` and pathspec elements,
64 which are allowed after a double hyphen `--` for disambiguation.
66 save [-p|--patch] [-S|--staged] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
68         This option is deprecated in favour of 'git stash push'.  It
69         differs from "stash push" in that it cannot take pathspec.
70         Instead, all non-option arguments are concatenated to form the stash
71         message.
73 list [<log-options>]::
75         List the stash entries that you currently have.  Each 'stash entry' is
76         listed with its name (e.g. `stash@{0}` is the latest entry, `stash@{1}` is
77         the one before, etc.), the name of the branch that was current when the
78         entry was made, and a short description of the commit the entry was
79         based on.
81 ----------------------------------------------------------------
82 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
83 stash@{1}: On master: 9cc0589... Add git-stash
84 ----------------------------------------------------------------
86 The command takes options applicable to the 'git log'
87 command to control what is shown and how. See linkgit:git-log[1].
89 show [-u|--include-untracked|--only-untracked] [<diff-options>] [<stash>]::
91         Show the changes recorded in the stash entry as a diff between the
92         stashed contents and the commit back when the stash entry was first
93         created.
94         By default, the command shows the diffstat, but it will accept any
95         format known to 'git diff' (e.g., `git stash show -p stash@{1}`
96         to view the second most recent entry in patch form).
97         If no `<diff-option>` is provided, the default behavior will be given
98         by the `stash.showStat`, and `stash.showPatch` config variables. You
99         can also use `stash.showIncludeUntracked` to set whether
100         `--include-untracked` is enabled by default.
102 pop [--index] [-q|--quiet] [<stash>]::
104         Remove a single stashed state from the stash list and apply it
105         on top of the current working tree state, i.e., do the inverse
106         operation of `git stash push`. The working directory must
107         match the index.
109 Applying the state can fail with conflicts; in this case, it is not
110 removed from the stash list. You need to resolve the conflicts by hand
111 and call `git stash drop` manually afterwards.
113 apply [--index] [-q|--quiet] [<stash>]::
115         Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
116         `<stash>` may be any commit that looks like a commit created by
117         `stash push` or `stash create`.
119 branch <branchname> [<stash>]::
121         Creates and checks out a new branch named `<branchname>` starting from
122         the commit at which the `<stash>` was originally created, applies the
123         changes recorded in `<stash>` to the new working tree and index.
124         If that succeeds, and `<stash>` is a reference of the form
125         `stash@{<revision>}`, it then drops the `<stash>`.
127 This is useful if the branch on which you ran `git stash push` has
128 changed enough that `git stash apply` fails due to conflicts. Since
129 the stash entry is applied on top of the commit that was HEAD at the
130 time `git stash` was run, it restores the originally stashed state
131 with no conflicts.
133 clear::
134         Remove all the stash entries. Note that those entries will then
135         be subject to pruning, and may be impossible to recover (see
136         'Examples' below for a possible strategy).
138 drop [-q|--quiet] [<stash>]::
140         Remove a single stash entry from the list of stash entries.
142 create::
144         Create a stash entry (which is a regular commit object) and
145         return its object name, without storing it anywhere in the ref
146         namespace.
147         This is intended to be useful for scripts.  It is probably not
148         the command you want to use; see "push" above.
150 store::
152         Store a given stash created via 'git stash create' (which is a
153         dangling merge commit) in the stash ref, updating the stash
154         reflog.  This is intended to be useful for scripts.  It is
155         probably not the command you want to use; see "push" above.
157 OPTIONS
158 -------
159 -a::
160 --all::
161         This option is only valid for `push` and `save` commands.
163 All ignored and untracked files are also stashed and then cleaned
164 up with `git clean`.
166 -u::
167 --include-untracked::
168 --no-include-untracked::
169         When used with the `push` and `save` commands,
170         all untracked files are also stashed and then cleaned up with
171         `git clean`.
173 When used with the `show` command, show the untracked files in the stash
174 entry as part of the diff.
176 --only-untracked::
177         This option is only valid for the `show` command.
179 Show only the untracked files in the stash entry as part of the diff.
181 --index::
182         This option is only valid for `pop` and `apply` commands.
184 Tries to reinstate not only the working tree's changes, but also
185 the index's ones. However, this can fail, when you have conflicts
186 (which are stored in the index, where you therefore can no longer
187 apply the changes as they were originally).
189 -k::
190 --keep-index::
191 --no-keep-index::
192         This option is only valid for `push` and `save` commands.
194 All changes already added to the index are left intact.
196 -p::
197 --patch::
198         This option is only valid for `push` and `save` commands.
200 Interactively select hunks from the diff between HEAD and the
201 working tree to be stashed.  The stash entry is constructed such
202 that its index state is the same as the index state of your
203 repository, and its worktree contains only the changes you selected
204 interactively.  The selected changes are then rolled back from your
205 worktree. See the ``Interactive Mode'' section of linkgit:git-add[1]
206 to learn how to operate the `--patch` mode.
208 The `--patch` option implies `--keep-index`.  You can use
209 `--no-keep-index` to override this.
211 -S::
212 --staged::
213         This option is only valid for `push` and `save` commands.
215 Stash only the changes that are currently staged. This is similar to
216 basic `git commit` except the state is committed to the stash instead
217 of current branch.
219 The `--patch` option has priority over this one.
221 --pathspec-from-file=<file>::
222         This option is only valid for `push` command.
224 Pathspec is passed in `<file>` instead of commandline args. If
225 `<file>` is exactly `-` then standard input is used. Pathspec
226 elements are separated by LF or CR/LF. Pathspec elements can be
227 quoted as explained for the configuration variable `core.quotePath`
228 (see linkgit:git-config[1]). See also `--pathspec-file-nul` and
229 global `--literal-pathspecs`.
231 --pathspec-file-nul::
232         This option is only valid for `push` command.
234 Only meaningful with `--pathspec-from-file`. Pathspec elements are
235 separated with NUL character and all other characters are taken
236 literally (including newlines and quotes).
238 -q::
239 --quiet::
240         This option is only valid for `apply`, `drop`, `pop`, `push`,
241         `save`, `store` commands.
243 Quiet, suppress feedback messages.
245 \--::
246         This option is only valid for `push` command.
248 Separates pathspec from options for disambiguation purposes.
250 <pathspec>...::
251         This option is only valid for `push` command.
253 The new stash entry records the modified states only for the files
254 that match the pathspec.  The index entries and working tree files
255 are then rolled back to the state in HEAD only for these files,
256 too, leaving files that do not match the pathspec intact.
258 For more details, see the 'pathspec' entry in linkgit:gitglossary[7].
260 <stash>::
261         This option is only valid for `apply`, `branch`, `drop`, `pop`,
262         `show` commands.
264 A reference of the form `stash@{<revision>}`. When no `<stash>` is
265 given, the latest stash is assumed (that is, `stash@{0}`).
267 DISCUSSION
268 ----------
270 A stash entry is represented as a commit whose tree records the state
271 of the working directory, and its first parent is the commit at `HEAD`
272 when the entry was created.  The tree of the second parent records the
273 state of the index when the entry is made, and it is made a child of
274 the `HEAD` commit.  The ancestry graph looks like this:
276             .----W
277            /    /
278      -----H----I
280 where `H` is the `HEAD` commit, `I` is a commit that records the state
281 of the index, and `W` is a commit that records the state of the working
282 tree.
285 EXAMPLES
286 --------
288 Pulling into a dirty tree::
290 When you are in the middle of something, you learn that there are
291 upstream changes that are possibly relevant to what you are
292 doing.  When your local changes do not conflict with the changes in
293 the upstream, a simple `git pull` will let you move forward.
295 However, there are cases in which your local changes do conflict with
296 the upstream changes, and `git pull` refuses to overwrite your
297 changes.  In such a case, you can stash your changes away,
298 perform a pull, and then unstash, like this:
300 ----------------------------------------------------------------
301 $ git pull
302  ...
303 file foobar not up to date, cannot merge.
304 $ git stash
305 $ git pull
306 $ git stash pop
307 ----------------------------------------------------------------
309 Interrupted workflow::
311 When you are in the middle of something, your boss comes in and
312 demands that you fix something immediately.  Traditionally, you would
313 make a commit to a temporary branch to store your changes away, and
314 return to your original branch to make the emergency fix, like this:
316 ----------------------------------------------------------------
317 # ... hack hack hack ...
318 $ git switch -c my_wip
319 $ git commit -a -m "WIP"
320 $ git switch master
321 $ edit emergency fix
322 $ git commit -a -m "Fix in a hurry"
323 $ git switch my_wip
324 $ git reset --soft HEAD^
325 # ... continue hacking ...
326 ----------------------------------------------------------------
328 You can use 'git stash' to simplify the above, like this:
330 ----------------------------------------------------------------
331 # ... hack hack hack ...
332 $ git stash
333 $ edit emergency fix
334 $ git commit -a -m "Fix in a hurry"
335 $ git stash pop
336 # ... continue hacking ...
337 ----------------------------------------------------------------
339 Testing partial commits::
341 You can use `git stash push --keep-index` when you want to make two or
342 more commits out of the changes in the work tree, and you want to test
343 each change before committing:
345 ----------------------------------------------------------------
346 # ... hack hack hack ...
347 $ git add --patch foo            # add just first part to the index
348 $ git stash push --keep-index    # save all other changes to the stash
349 $ edit/build/test first part
350 $ git commit -m 'First part'     # commit fully tested change
351 $ git stash pop                  # prepare to work on all other changes
352 # ... repeat above five steps until one commit remains ...
353 $ edit/build/test remaining parts
354 $ git commit foo -m 'Remaining parts'
355 ----------------------------------------------------------------
357 Saving unrelated changes for future use::
359 When you are in the middle of massive changes and you find some
360 unrelated issue that you don't want to forget to fix, you can do the
361 change(s), stage them, and use `git stash push --staged` to stash them
362 out for future use. This is similar to committing the staged changes,
363 only the commit ends-up being in the stash and not on the current branch.
365 ----------------------------------------------------------------
366 # ... hack hack hack ...
367 $ git add --patch foo           # add unrelated changes to the index
368 $ git stash push --staged       # save these changes to the stash
369 # ... hack hack hack, finish current changes ...
370 $ git commit -m 'Massive'       # commit fully tested changes
371 $ git switch fixup-branch       # switch to another branch
372 $ git stash pop                 # to finish work on the saved changes
373 ----------------------------------------------------------------
375 Recovering stash entries that were cleared/dropped erroneously::
377 If you mistakenly drop or clear stash entries, they cannot be recovered
378 through the normal safety mechanisms.  However, you can try the
379 following incantation to get a list of stash entries that are still in
380 your repository, but not reachable any more:
382 ----------------------------------------------------------------
383 git fsck --unreachable |
384 grep commit | cut -d\  -f3 |
385 xargs git log --merges --no-walk --grep=WIP
386 ----------------------------------------------------------------
388 CONFIGURATION
389 -------------
391 include::includes/cmd-config-section-all.txt[]
393 include::config/stash.txt[]
396 SEE ALSO
397 --------
398 linkgit:git-checkout[1],
399 linkgit:git-commit[1],
400 linkgit:git-reflog[1],
401 linkgit:git-reset[1],
402 linkgit:git-switch[1]
406 Part of the linkgit:git[1] suite