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