| blob | 16af38436fd72dc17a7e276c181f8474bf9e49da |
1 '\" t
2 .\" Title: git-stash
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 04/25/2023
6 .\" Manual: Git Manual
7 .\" Source: Git 2.40.1.423.g2807bd2c10
8 .\" Language: English
9 .\"
10 .TH "GIT\-STASH" "1" "04/25/2023" "Git 2\&.40\&.1\&.423\&.g2807bd" "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 .sp
52 .SH "DESCRIPTION"
53 .sp
54 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\&.
55 .sp
56 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\&.
57 .sp
58 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)\&.
59 .SH "COMMANDS"
60 .PP
61 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>\&...]
62 .RS 4
63 Save your local modifications to a new
64 \fIstash entry\fR
65 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\&.
66 .sp
67 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
68 \fBstash \-p\fR
69 which acts as alias for
70 \fBstash push \-p\fR
71 and pathspec elements, which are allowed after a double hyphen
72 \fB\-\-\fR
73 for disambiguation\&.
74 .RE
75 .PP
76 save [\-p|\-\-patch] [\-S|\-\-staged] [\-k|\-\-[no\-]keep\-index] [\-u|\-\-include\-untracked] [\-a|\-\-all] [\-q|\-\-quiet] [<message>]
77 .RS 4
78 This option is deprecated in favour of
79 \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\&.
80 .RE
81 .PP
82 list [<log\-options>]
83 .RS 4
84 List the stash entries that you currently have\&. Each
85 \fIstash entry\fR
86 is listed with its name (e\&.g\&.
87 \fBstash@{0}\fR
88 is the latest entry,
89 \fBstash@{1}\fR
90 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\&.
91 .sp
92 .if n \{\
93 .RS 4
94 .\}
95 .nf
96 stash@{0}: WIP on submit: 6ebd0e2\&.\&.\&. Update git\-stash documentation
97 stash@{1}: On master: 9cc0589\&.\&.\&. Add git\-stash
98 .fi
99 .if n \{\
100 .RE
101 .\}
102 .sp
103 The command takes options applicable to the
104 \fIgit log\fR
105 command to control what is shown and how\&. See
106 \fBgit-log\fR(1)\&.
107 .RE
108 .PP
109 show [\-u|\-\-include\-untracked|\-\-only\-untracked] [<diff\-options>] [<stash>]
110 .RS 4
111 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
112 \fIgit diff\fR
113 (e\&.g\&.,
114 \fBgit stash show \-p stash@{1}\fR
115 to view the second most recent entry in patch form)\&. If no
116 \fB<diff\-option>\fR
117 is provided, the default behavior will be given by the
118 \fBstash\&.showStat\fR, and
119 \fBstash\&.showPatch\fR
120 config variables\&. You can also use
121 \fBstash\&.showIncludeUntracked\fR
122 to set whether
123 \fB\-\-include\-untracked\fR
124 is enabled by default\&.
125 .RE
126 .PP
127 pop [\-\-index] [\-q|\-\-quiet] [<stash>]
128 .RS 4
129 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
130 \fBgit stash push\fR\&. The working directory must match the index\&.
131 .sp
132 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
133 \fBgit stash drop\fR
134 manually afterwards\&.
135 .RE
136 .PP
137 apply [\-\-index] [\-q|\-\-quiet] [<stash>]
138 .RS 4
139 Like
140 \fBpop\fR, but do not remove the state from the stash list\&. Unlike
141 \fBpop\fR,
142 \fB<stash>\fR
143 may be any commit that looks like a commit created by
144 \fBstash push\fR
145 or
146 \fBstash create\fR\&.
147 .RE
148 .PP
149 branch <branchname> [<stash>]
150 .RS 4
151 Creates and checks out a new branch named
152 \fB<branchname>\fR
153 starting from the commit at which the
154 \fB<stash>\fR
155 was originally created, applies the changes recorded in
156 \fB<stash>\fR
157 to the new working tree and index\&. If that succeeds, and
158 \fB<stash>\fR
159 is a reference of the form
160 \fBstash@{<revision>}\fR, it then drops the
161 \fB<stash>\fR\&.
162 .sp
163 This is useful if the branch on which you ran
164 \fBgit stash push\fR
165 has changed enough that
166 \fBgit stash apply\fR
167 fails due to conflicts\&. Since the stash entry is applied on top of the commit that was HEAD at the time
168 \fBgit stash\fR
169 was run, it restores the originally stashed state with no conflicts\&.
170 .RE
171 .PP
172 clear
173 .RS 4
174 Remove all the stash entries\&. Note that those entries will then be subject to pruning, and may be impossible to recover (see
175 \fIExamples\fR
176 below for a possible strategy)\&.
177 .RE
178 .PP
179 drop [\-q|\-\-quiet] [<stash>]
180 .RS 4
181 Remove a single stash entry from the list of stash entries\&.
182 .RE
183 .PP
184 create
185 .RS 4
186 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\&.
187 .RE
188 .PP
189 store
190 .RS 4
191 Store a given stash created via
192 \fIgit stash create\fR
193 (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\&.
194 .RE
195 .SH "OPTIONS"
196 .PP
197 \-a, \-\-all
198 .RS 4
199 This option is only valid for
200 \fBpush\fR
201 and
202 \fBsave\fR
203 commands\&.
204 .sp
205 All ignored and untracked files are also stashed and then cleaned up with
206 \fBgit clean\fR\&.
207 .RE
208 .PP
209 \-u, \-\-include\-untracked, \-\-no\-include\-untracked
210 .RS 4
211 When used with the
212 \fBpush\fR
213 and
214 \fBsave\fR
215 commands, all untracked files are also stashed and then cleaned up with
216 \fBgit clean\fR\&.
217 .sp
218 When used with the
219 \fBshow\fR
220 command, show the untracked files in the stash entry as part of the diff\&.
221 .RE
222 .PP
223 \-\-only\-untracked
224 .RS 4
225 This option is only valid for the
226 \fBshow\fR
227 command\&.
228 .sp
229 Show only the untracked files in the stash entry as part of the diff\&.
230 .RE
231 .PP
232 \-\-index
233 .RS 4
234 This option is only valid for
235 \fBpop\fR
236 and
237 \fBapply\fR
238 commands\&.
239 .sp
240 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)\&.
241 .RE
242 .PP
243 \-k, \-\-keep\-index, \-\-no\-keep\-index
244 .RS 4
245 This option is only valid for
246 \fBpush\fR
247 and
248 \fBsave\fR
249 commands\&.
250 .sp
251 All changes already added to the index are left intact\&.
252 .RE
253 .PP
254 \-p, \-\-patch
255 .RS 4
256 This option is only valid for
257 \fBpush\fR
258 and
259 \fBsave\fR
260 commands\&.
261 .sp
262 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 \(lqInteractive Mode\(rq section of
263 \fBgit-add\fR(1)
264 to learn how to operate the
265 \fB\-\-patch\fR
266 mode\&.
267 .sp
268 The
269 \fB\-\-patch\fR
270 option implies
271 \fB\-\-keep\-index\fR\&. You can use
272 \fB\-\-no\-keep\-index\fR
273 to override this\&.
274 .RE
275 .PP
276 \-S, \-\-staged
277 .RS 4
278 This option is only valid for
279 \fBpush\fR
280 and
281 \fBsave\fR
282 commands\&.
283 .sp
284 Stash only the changes that are currently staged\&. This is similar to basic
285 \fBgit commit\fR
286 except the state is committed to the stash instead of current branch\&.
287 .sp
288 The
289 \fB\-\-patch\fR
290 option has priority over this one\&.
291 .RE
292 .PP
293 \-\-pathspec\-from\-file=<file>
294 .RS 4
295 This option is only valid for
296 \fBpush\fR
297 command\&.
298 .sp
299 Pathspec is passed in
300 \fB<file>\fR
301 instead of commandline args\&. If
302 \fB<file>\fR
303 is exactly
304 \fB\-\fR
305 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
306 \fBcore\&.quotePath\fR
307 (see
308 \fBgit-config\fR(1))\&. See also
309 \fB\-\-pathspec\-file\-nul\fR
310 and global
311 \fB\-\-literal\-pathspecs\fR\&.
312 .RE
313 .PP
314 \-\-pathspec\-file\-nul
315 .RS 4
316 This option is only valid for
317 \fBpush\fR
318 command\&.
319 .sp
320 Only meaningful with
321 \fB\-\-pathspec\-from\-file\fR\&. Pathspec elements are separated with NUL character and all other characters are taken literally (including newlines and quotes)\&.
322 .RE
323 .PP
324 \-q, \-\-quiet
325 .RS 4
326 This option is only valid for
327 \fBapply\fR,
328 \fBdrop\fR,
329 \fBpop\fR,
330 \fBpush\fR,
331 \fBsave\fR,
332 \fBstore\fR
333 commands\&.
334 .sp
335 Quiet, suppress feedback messages\&.
336 .RE
337 .PP
338 \-\-
339 .RS 4
340 This option is only valid for
341 \fBpush\fR
342 command\&.
343 .sp
344 Separates pathspec from options for disambiguation purposes\&.
345 .RE
346 .PP
347 <pathspec>\&...
348 .RS 4
349 This option is only valid for
350 \fBpush\fR
351 command\&.
352 .sp
353 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\&.
354 .sp
355 For more details, see the
356 \fIpathspec\fR
357 entry in
358 \fBgitglossary\fR(7)\&.
359 .RE
360 .PP
361 <stash>
362 .RS 4
363 This option is only valid for
364 \fBapply\fR,
365 \fBbranch\fR,
366 \fBdrop\fR,
367 \fBpop\fR,
368 \fBshow\fR
369 commands\&.
370 .sp
371 A reference of the form
372 \fBstash@{<revision>}\fR\&. When no
373 \fB<stash>\fR
374 is given, the latest stash is assumed (that is,
375 \fBstash@{0}\fR)\&.
376 .RE
377 .SH "DISCUSSION"
378 .sp
379 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:
380 .sp
381 .if n \{\
382 .RS 4
383 .\}
384 .nf
385 \&.\-\-\-\-W
386 / /
387 \-\-\-\-\-H\-\-\-\-I
388 .fi
389 .if n \{\
390 .RE
391 .\}
392 .sp
393 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\&.
394 .SH "EXAMPLES"
395 .PP
396 Pulling into a dirty tree
397 .RS 4
398 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
399 \fBgit pull\fR
400 will let you move forward\&.
401 .sp
402 However, there are cases in which your local changes do conflict with the upstream changes, and
403 \fBgit pull\fR
404 refuses to overwrite your changes\&. In such a case, you can stash your changes away, perform a pull, and then unstash, like this:
405 .sp
406 .if n \{\
407 .RS 4
408 .\}
409 .nf
410 $ git pull
411 \&.\&.\&.
412 file foobar not up to date, cannot merge\&.
413 $ git stash
414 $ git pull
415 $ git stash pop
416 .fi
417 .if n \{\
418 .RE
419 .\}
420 .sp
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 .sp
464 .RE
465 .PP
466 Testing partial commits
467 .RS 4
468 You can use
469 \fBgit stash push \-\-keep\-index\fR
470 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:
471 .sp
472 .if n \{\
473 .RS 4
474 .\}
475 .nf
476 # \&.\&.\&. hack hack hack \&.\&.\&.
477 $ git add \-\-patch foo # add just first part to the index
478 $ git stash push \-\-keep\-index # save all other changes to the stash
479 $ edit/build/test first part
480 $ git commit \-m \*(AqFirst part\*(Aq # commit fully tested change
481 $ git stash pop # prepare to work on all other changes
482 # \&.\&.\&. repeat above five steps until one commit remains \&.\&.\&.
483 $ edit/build/test remaining parts
484 $ git commit foo \-m \*(AqRemaining parts\*(Aq
485 .fi
486 .if n \{\
487 .RE
488 .\}
489 .sp
490 .RE
491 .PP
492 Saving unrelated changes for future use
493 .RS 4
494 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
495 \fBgit stash push \-\-staged\fR
496 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\&.
497 .sp
498 .if n \{\
499 .RS 4
500 .\}
501 .nf
502 # \&.\&.\&. hack hack hack \&.\&.\&.
503 $ git add \-\-patch foo # add unrelated changes to the index
504 $ git stash push \-\-staged # save these changes to the stash
505 # \&.\&.\&. hack hack hack, finish curent changes \&.\&.\&.
506 $ git commit \-m \*(AqMassive\*(Aq # commit fully tested changes
507 $ git switch fixup\-branch # switch to another branch
508 $ git stash pop # to finish work on the saved changes
509 .fi
510 .if n \{\
511 .RE
512 .\}
513 .sp
514 .RE
515 .PP
516 Recovering stash entries that were cleared/dropped erroneously
517 .RS 4
518 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:
519 .sp
520 .if n \{\
521 .RS 4
522 .\}
523 .nf
524 git fsck \-\-unreachable |
525 grep commit | cut \-d\e \-f3 |
526 xargs git log \-\-merges \-\-no\-walk \-\-grep=WIP
527 .fi
528 .if n \{\
529 .RE
530 .\}
531 .sp
532 .RE
533 .SH "CONFIGURATION"
534 .sp
535 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:
536 .PP
537 stash\&.showIncludeUntracked
538 .RS 4
539 If this is set to true, the
540 \fBgit stash show\fR
541 command will show the untracked files of a stash entry\&. Defaults to false\&. See description of
542 \fIshow\fR
543 command in
544 \fBgit-stash\fR(1)\&.
545 .RE
546 .PP
547 stash\&.showPatch
548 .RS 4
549 If this is set to true, the
550 \fBgit stash show\fR
551 command without an option will show the stash entry in patch form\&. Defaults to false\&. See description of
552 \fIshow\fR
553 command in
554 \fBgit-stash\fR(1)\&.
555 .RE
556 .PP
557 stash\&.showStat
558 .RS 4
559 If this is set to true, the
560 \fBgit stash show\fR
561 command without an option will show diffstat of the stash entry\&. Defaults to true\&. See description of
562 \fIshow\fR
563 command in
564 \fBgit-stash\fR(1)\&.
565 .RE
566 .SH "SEE ALSO"
567 .sp
568 \fBgit-checkout\fR(1), \fBgit-commit\fR(1), \fBgit-reflog\fR(1), \fBgit-reset\fR(1), \fBgit-switch\fR(1)
569 .SH "GIT"
570 .sp
571 Part of the \fBgit\fR(1) suite