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