| blob | 3887334e587331d5df1d221a8a17d6e62bc3c97d |
1 '\" t
2 .\" Title: git-stash
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 2024-09-23
6 .\" Manual: Git Manual
7 .\" Source: Git 2.46.2.628.g6258f68c3c
8 .\" Language: English
9 .\"
10 .TH "GIT\-STASH" "1" "2024-09-23" "Git 2\&.46\&.2\&.628\&.g6258f6" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-stash \- Stash the changes in a dirty working directory away
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit stash\fR list [<log\-options>]
36 \fIgit stash\fR show [\-u | \-\-include\-untracked | \-\-only\-untracked] [<diff\-options>] [<stash>]
37 \fIgit stash\fR drop [\-q | \-\-quiet] [<stash>]
38 \fIgit stash\fR pop [\-\-index] [\-q | \-\-quiet] [<stash>]
39 \fIgit stash\fR apply [\-\-index] [\-q | \-\-quiet] [<stash>]
40 \fIgit stash\fR branch <branchname> [<stash>]
41 \fIgit stash\fR [push [\-p | \-\-patch] [\-S | \-\-staged] [\-k | \-\-[no\-]keep\-index] [\-q | \-\-quiet]
42 [\-u | \-\-include\-untracked] [\-a | \-\-all] [(\-m | \-\-message) <message>]
43 [\-\-pathspec\-from\-file=<file> [\-\-pathspec\-file\-nul]]
44 [\-\-] [<pathspec>\&...\:]]
45 \fIgit stash\fR save [\-p | \-\-patch] [\-S | \-\-staged] [\-k | \-\-[no\-]keep\-index] [\-q | \-\-quiet]
46 [\-u | \-\-include\-untracked] [\-a | \-\-all] [<message>]
47 \fIgit stash\fR clear
48 \fIgit stash\fR create [<message>]
49 \fIgit stash\fR store [(\-m | \-\-message) <message>] [\-q | \-\-quiet] <commit>
50 .fi
51 .SH "DESCRIPTION"
52 .sp
53 Use \fBgit stash\fR when you want to record the current state of the 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 \fBHEAD\fR commit\&.
54 .sp
55 The modifications stashed away by this command can be listed with \fBgit stash list\fR, inspected with \fBgit stash show\fR, and restored (potentially on top of a different commit) with \fBgit stash apply\fR\&. Calling \fBgit stash\fR without any arguments is equivalent to \fBgit stash push\fR\&. A stash is by default listed as "WIP on \fIbranchname\fR \&...\:", but you can give a more descriptive message on the command line when you create one\&.
56 .sp
57 The latest stash you created is stored in \fBrefs/stash\fR; older stashes are found in the reflog of this reference and can be named using the usual reflog syntax (e\&.g\&. \fBstash@{0}\fR is the most recently created stash, \fBstash@{1}\fR is the one before it, \fBstash@{2\&.hours\&.ago}\fR is also possible)\&. Stashes may also be referenced by specifying just the stash index (e\&.g\&. the integer \fBn\fR is equivalent to \fBstash@{n}\fR)\&.
58 .SH "COMMANDS"
59 .PP
60 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>\&...\:]
61 .RS 4
62 Save your local modifications to a new
63 \fIstash entry\fR
64 and roll them back to HEAD (in the working tree and in the index)\&. The <message> part is optional and gives the description along with the stashed state\&.
65 .sp
66 For quickly making a snapshot, you can omit "push"\&. In this mode, non\-option arguments are not allowed to prevent a misspelled subcommand from making an unwanted stash entry\&. The two exceptions to this are
67 \fBstash \-p\fR
68 which acts as alias for
69 \fBstash push \-p\fR
70 and pathspec elements, which are allowed after a double hyphen
71 \fB\-\-\fR
72 for disambiguation\&.
73 .RE
74 .PP
75 save [\-p|\-\-patch] [\-S|\-\-staged] [\-k|\-\-[no\-]keep\-index] [\-u|\-\-include\-untracked] [\-a|\-\-all] [\-q|\-\-quiet] [<message>]
76 .RS 4
77 This option is deprecated in favour of
78 \fIgit stash push\fR\&. It differs from "stash push" in that it cannot take pathspec\&. Instead, all non\-option arguments are concatenated to form the stash message\&.
79 .RE
80 .PP
81 list [<log\-options>]
82 .RS 4
83 List the stash entries that you currently have\&. Each
84 \fIstash entry\fR
85 is listed with its name (e\&.g\&.
86 \fBstash@{0}\fR
87 is the latest entry,
88 \fBstash@{1}\fR
89 is the one before, etc\&.), the name of the branch that was current when the entry was made, and a short description of the commit the entry was based on\&.
90 .sp
91 .if n \{\
92 .RS 4
93 .\}
94 .nf
95 stash@{0}: WIP on submit: 6ebd0e2\&.\&.\&. Update git\-stash documentation
96 stash@{1}: On master: 9cc0589\&.\&.\&. Add git\-stash
97 .fi
98 .if n \{\
99 .RE
100 .\}
101 .sp
102 The command takes options applicable to the
103 \fIgit log\fR
104 command to control what is shown and how\&. See
105 \fBgit-log\fR(1)\&.
106 .RE
107 .PP
108 show [\-u|\-\-include\-untracked|\-\-only\-untracked] [<diff\-options>] [<stash>]
109 .RS 4
110 Show the changes recorded in the stash entry as a diff between the stashed contents and the commit back when the stash entry was first created\&. By default, the command shows the diffstat, but it will accept any format known to
111 \fIgit diff\fR
112 (e\&.g\&.,
113 \fBgit stash show \-p stash@{1}\fR
114 to view the second most recent entry in patch form)\&. If no
115 \fB<diff\-option>\fR
116 is provided, the default behavior will be given by the
117 \fBstash\&.showStat\fR, and
118 \fBstash\&.showPatch\fR
119 config variables\&. You can also use
120 \fBstash\&.showIncludeUntracked\fR
121 to set whether
122 \fB\-\-include\-untracked\fR
123 is enabled by default\&.
124 .RE
125 .PP
126 pop [\-\-index] [\-q|\-\-quiet] [<stash>]
127 .RS 4
128 Remove a single stashed state from the stash list and apply it on top of the current working tree state, i\&.e\&., do the inverse operation of
129 \fBgit stash push\fR\&. The working directory must match the index\&.
130 .sp
131 Applying the state can fail with conflicts; in this case, it is not removed from the stash list\&. You need to resolve the conflicts by hand and call
132 \fBgit stash drop\fR
133 manually afterwards\&.
134 .RE
135 .PP
136 apply [\-\-index] [\-q|\-\-quiet] [<stash>]
137 .RS 4
138 Like
139 \fBpop\fR, but do not remove the state from the stash list\&. Unlike
140 \fBpop\fR,
141 \fB<stash>\fR
142 may be any commit that looks like a commit created by
143 \fBstash push\fR
144 or
145 \fBstash create\fR\&.
146 .RE
147 .PP
148 branch <branchname> [<stash>]
149 .RS 4
150 Creates and checks out a new branch named
151 \fB<branchname>\fR
152 starting from the commit at which the
153 \fB<stash>\fR
154 was originally created, applies the changes recorded in
155 \fB<stash>\fR
156 to the new working tree and index\&. If that succeeds, and
157 \fB<stash>\fR
158 is a reference of the form
159 \fBstash@{<revision>}\fR, it then drops the
160 \fB<stash>\fR\&.
161 .sp
162 This is useful if the branch on which you ran
163 \fBgit stash push\fR
164 has changed enough that
165 \fBgit stash apply\fR
166 fails due to conflicts\&. Since the stash entry is applied on top of the commit that was HEAD at the time
167 \fBgit stash\fR
168 was run, it restores the originally stashed state with no conflicts\&.
169 .RE
170 .PP
171 clear
172 .RS 4
173 Remove all the stash entries\&. Note that those entries will then be subject to pruning, and may be impossible to recover (see
174 \fIExamples\fR
175 below for a possible strategy)\&.
176 .RE
177 .PP
178 drop [\-q|\-\-quiet] [<stash>]
179 .RS 4
180 Remove a single stash entry from the list of stash entries\&.
181 .RE
182 .PP
183 create
184 .RS 4
185 Create a stash entry (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace\&. This is intended to be useful for scripts\&. It is probably not the command you want to use; see "push" above\&.
186 .RE
187 .PP
188 store
189 .RS 4
190 Store a given stash created via
191 \fIgit stash create\fR
192 (which is a dangling merge commit) in the stash ref, updating the stash reflog\&. This is intended to be useful for scripts\&. It is probably not the command you want to use; see "push" above\&.
193 .RE
194 .SH "OPTIONS"
195 .PP
196 \-a, \-\-all
197 .RS 4
198 This option is only valid for
199 \fBpush\fR
200 and
201 \fBsave\fR
202 commands\&.
203 .sp
204 All ignored and untracked files are also stashed and then cleaned up with
205 \fBgit clean\fR\&.
206 .RE
207 .PP
208 \-u, \-\-include\-untracked, \-\-no\-include\-untracked
209 .RS 4
210 When used with the
211 \fBpush\fR
212 and
213 \fBsave\fR
214 commands, all untracked files are also stashed and then cleaned up with
215 \fBgit clean\fR\&.
216 .sp
217 When used with the
218 \fBshow\fR
219 command, show the untracked files in the stash entry as part of the diff\&.
220 .RE
221 .PP
222 \-\-only\-untracked
223 .RS 4
224 This option is only valid for the
225 \fBshow\fR
226 command\&.
227 .sp
228 Show only the untracked files in the stash entry as part of the diff\&.
229 .RE
230 .PP
231 \-\-index
232 .RS 4
233 This option is only valid for
234 \fBpop\fR
235 and
236 \fBapply\fR
237 commands\&.
238 .sp
239 Tries to reinstate not only the working tree\(cqs changes, but also the index\(cqs 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)\&.
240 .RE
241 .PP
242 \-k, \-\-keep\-index, \-\-no\-keep\-index
243 .RS 4
244 This option is only valid for
245 \fBpush\fR
246 and
247 \fBsave\fR
248 commands\&.
249 .sp
250 All changes already added to the index are left intact\&.
251 .RE
252 .PP
253 \-p, \-\-patch
254 .RS 4
255 This option is only valid for
256 \fBpush\fR
257 and
258 \fBsave\fR
259 commands\&.
260 .sp
261 Interactively select hunks from the diff between HEAD and the working tree to be stashed\&. The stash entry is constructed such that its index state is the same as the index state of your repository, and its worktree contains only the changes you selected interactively\&. The selected changes are then rolled back from your worktree\&. See the
262 \(lqInteractive Mode\(rq
263 section of
264 \fBgit-add\fR(1)
265 to learn how to operate the
266 \fB\-\-patch\fR
267 mode\&.
268 .sp
269 The
270 \fB\-\-patch\fR
271 option implies
272 \fB\-\-keep\-index\fR\&. You can use
273 \fB\-\-no\-keep\-index\fR
274 to override this\&.
275 .RE
276 .PP
277 \-S, \-\-staged
278 .RS 4
279 This option is only valid for
280 \fBpush\fR
281 and
282 \fBsave\fR
283 commands\&.
284 .sp
285 Stash only the changes that are currently staged\&. This is similar to basic
286 \fBgit commit\fR
287 except the state is committed to the stash instead of current branch\&.
288 .sp
289 The
290 \fB\-\-patch\fR
291 option has priority over this one\&.
292 .RE
293 .PP
294 \-\-pathspec\-from\-file=<file>
295 .RS 4
296 This option is only valid for
297 \fBpush\fR
298 command\&.
299 .sp
300 Pathspec is passed in
301 \fB<file>\fR
302 instead of commandline args\&. If
303 \fB<file>\fR
304 is exactly
305 \fB\-\fR
306 then standard input is used\&. Pathspec elements are separated by LF or CR/LF\&. Pathspec elements can be quoted as explained for the configuration variable
307 \fBcore\&.quotePath\fR
308 (see
309 \fBgit-config\fR(1))\&. See also
310 \fB\-\-pathspec\-file\-nul\fR
311 and global
312 \fB\-\-literal\-pathspecs\fR\&.
313 .RE
314 .PP
315 \-\-pathspec\-file\-nul
316 .RS 4
317 This option is only valid for
318 \fBpush\fR
319 command\&.
320 .sp
321 Only meaningful with
322 \fB\-\-pathspec\-from\-file\fR\&. Pathspec elements are separated with NUL character and all other characters are taken literally (including newlines and quotes)\&.
323 .RE
324 .PP
325 \-q, \-\-quiet
326 .RS 4
327 This option is only valid for
328 \fBapply\fR,
329 \fBdrop\fR,
330 \fBpop\fR,
331 \fBpush\fR,
332 \fBsave\fR,
333 \fBstore\fR
334 commands\&.
335 .sp
336 Quiet, suppress feedback messages\&.
337 .RE
338 .PP
339 \-\-
340 .RS 4
341 This option is only valid for
342 \fBpush\fR
343 command\&.
344 .sp
345 Separates pathspec from options for disambiguation purposes\&.
346 .RE
347 .PP
348 <pathspec>\&...\:
349 .RS 4
350 This option is only valid for
351 \fBpush\fR
352 command\&.
353 .sp
354 The new stash entry records the modified states only for the files that match the pathspec\&. The index entries and working tree files are then rolled back to the state in HEAD only for these files, too, leaving files that do not match the pathspec intact\&.
355 .sp
356 For more details, see the
357 \fIpathspec\fR
358 entry in
359 \fBgitglossary\fR(7)\&.
360 .RE
361 .PP
362 <stash>
363 .RS 4
364 This option is only valid for
365 \fBapply\fR,
366 \fBbranch\fR,
367 \fBdrop\fR,
368 \fBpop\fR,
369 \fBshow\fR
370 commands\&.
371 .sp
372 A reference of the form
373 \fBstash@{<revision>}\fR\&. When no
374 \fB<stash>\fR
375 is given, the latest stash is assumed (that is,
376 \fBstash@{0}\fR)\&.
377 .RE
378 .SH "DISCUSSION"
379 .sp
380 A stash entry is represented as a commit whose tree records the state of the working directory, and its first parent is the commit at \fBHEAD\fR when the entry was created\&. The tree of the second parent records the state of the index when the entry is made, and it is made a child of the \fBHEAD\fR commit\&. The ancestry graph looks like this:
381 .sp
382 .if n \{\
383 .RS 4
384 .\}
385 .nf
386 \&.\-\-\-\-W
387 / /
388 \-\-\-\-\-H\-\-\-\-I
389 .fi
390 .if n \{\
391 .RE
392 .\}
393 .sp
394 where \fBH\fR is the \fBHEAD\fR commit, \fBI\fR is a commit that records the state of the index, and \fBW\fR is a commit that records the state of the working tree\&.
395 .SH "EXAMPLES"
396 .PP
397 Pulling into a dirty tree
398 .RS 4
399 When you are in the middle of something, you learn that there are upstream changes that are possibly relevant to what you are doing\&. When your local changes do not conflict with the changes in the upstream, a simple
400 \fBgit pull\fR
401 will let you move forward\&.
402 .sp
403 However, there are cases in which your local changes do conflict with the upstream changes, and
404 \fBgit pull\fR
405 refuses to overwrite your changes\&. In such a case, you can stash your changes away, perform a pull, and then unstash, like this:
406 .sp
407 .if n \{\
408 .RS 4
409 .\}
410 .nf
411 $ git pull
412 \&.\&.\&.
413 file foobar not up to date, cannot merge\&.
414 $ git stash
415 $ git pull
416 $ git stash pop
417 .fi
418 .if n \{\
419 .RE
420 .\}
421 .RE
422 .PP
423 Interrupted workflow
424 .RS 4
425 When you are in the middle of something, your boss comes in and demands that you fix something immediately\&. Traditionally, you would make a commit to a temporary branch to store your changes away, and return to your original branch to make the emergency fix, like this:
426 .sp
427 .if n \{\
428 .RS 4
429 .\}
430 .nf
431 # \&.\&.\&. hack hack hack \&.\&.\&.
432 $ git switch \-c my_wip
433 $ git commit \-a \-m "WIP"
434 $ git switch master
435 $ edit emergency fix
436 $ git commit \-a \-m "Fix in a hurry"
437 $ git switch my_wip
438 $ git reset \-\-soft HEAD^
439 # \&.\&.\&. continue hacking \&.\&.\&.
440 .fi
441 .if n \{\
442 .RE
443 .\}
444 .sp
445 You can use
446 \fIgit stash\fR
447 to simplify the above, like this:
448 .sp
449 .if n \{\
450 .RS 4
451 .\}
452 .nf
453 # \&.\&.\&. hack hack hack \&.\&.\&.
454 $ git stash
455 $ edit emergency fix
456 $ git commit \-a \-m "Fix in a hurry"
457 $ git stash pop
458 # \&.\&.\&. continue hacking \&.\&.\&.
459 .fi
460 .if n \{\
461 .RE
462 .\}
463 .RE
464 .PP
465 Testing partial commits
466 .RS 4
467 You can use
468 \fBgit stash push \-\-keep\-index\fR
469 when you want to make two or more commits out of the changes in the work tree, and you want to test each change before committing:
470 .sp
471 .if n \{\
472 .RS 4
473 .\}
474 .nf
475 # \&.\&.\&. hack hack hack \&.\&.\&.
476 $ git add \-\-patch foo # add just first part to the index
477 $ git stash push \-\-keep\-index # save all other changes to the stash
478 $ edit/build/test first part
479 $ git commit \-m \*(AqFirst part\*(Aq # commit fully tested change
480 $ git stash pop # prepare to work on all other changes
481 # \&.\&.\&. repeat above five steps until one commit remains \&.\&.\&.
482 $ edit/build/test remaining parts
483 $ git commit foo \-m \*(AqRemaining parts\*(Aq
484 .fi
485 .if n \{\
486 .RE
487 .\}
488 .RE
489 .PP
490 Saving unrelated changes for future use
491 .RS 4
492 When you are in the middle of massive changes and you find some unrelated issue that you don\(cqt want to forget to fix, you can do the change(s), stage them, and use
493 \fBgit stash push \-\-staged\fR
494 to stash them out for future use\&. This is similar to committing the staged changes, only the commit ends\-up being in the stash and not on the current branch\&.
495 .sp
496 .if n \{\
497 .RS 4
498 .\}
499 .nf
500 # \&.\&.\&. hack hack hack \&.\&.\&.
501 $ git add \-\-patch foo # add unrelated changes to the index
502 $ git stash push \-\-staged # save these changes to the stash
503 # \&.\&.\&. hack hack hack, finish current changes \&.\&.\&.
504 $ git commit \-m \*(AqMassive\*(Aq # commit fully tested changes
505 $ git switch fixup\-branch # switch to another branch
506 $ git stash pop # to finish work on the saved changes
507 .fi
508 .if n \{\
509 .RE
510 .\}
511 .RE
512 .PP
513 Recovering stash entries that were cleared/dropped erroneously
514 .RS 4
515 If you mistakenly drop or clear stash entries, they cannot be recovered through the normal safety mechanisms\&. However, you can try the following incantation to get a list of stash entries that are still in your repository, but not reachable any more:
516 .sp
517 .if n \{\
518 .RS 4
519 .\}
520 .nf
521 git fsck \-\-unreachable |
522 grep commit | cut \-d\e \-f3 |
523 xargs git log \-\-merges \-\-no\-walk \-\-grep=WIP
524 .fi
525 .if n \{\
526 .RE
527 .\}
528 .RE
529 .SH "CONFIGURATION"
530 .sp
531 Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
532 .PP
533 stash\&.showIncludeUntracked
534 .RS 4
535 If this is set to true, the
536 \fBgit stash show\fR
537 command will show the untracked files of a stash entry\&. Defaults to false\&. See the description of the
538 \fIshow\fR
539 command in
540 \fBgit-stash\fR(1)\&.
541 .RE
542 .PP
543 stash\&.showPatch
544 .RS 4
545 If this is set to true, the
546 \fBgit stash show\fR
547 command without an option will show the stash entry in patch form\&. Defaults to false\&. See the description of the
548 \fIshow\fR
549 command in
550 \fBgit-stash\fR(1)\&.
551 .RE
552 .PP
553 stash\&.showStat
554 .RS 4
555 If this is set to true, the
556 \fBgit stash show\fR
557 command without an option will show a diffstat of the stash entry\&. Defaults to true\&. See the description of the
558 \fIshow\fR
559 command in
560 \fBgit-stash\fR(1)\&.
561 .RE
562 .SH "SEE ALSO"
563 .sp
564 \fBgit-checkout\fR(1), \fBgit-commit\fR(1), \fBgit-reflog\fR(1), \fBgit-reset\fR(1), \fBgit-switch\fR(1)
565 .SH "GIT"
566 .sp
567 Part of the \fBgit\fR(1) suite