Documentation/git-stash.txt

   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 [verse]
  11 'git stash' list [<options>]
  12 'git stash' show [<stash>]
  13 'git stash' drop [-q|--quiet] [<stash>]
  14 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>]
  15 'git stash' branch <branchname> [<stash>]
  16 'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet]
  17              [-u|--include-untracked] [-a|--all] [<message>]]
  18 'git stash' clear
  19 'git stash' create [<message>]
  20 'git stash' store [-m|--message <message>] [-q|--quiet] <commit>
  21
  22 DESCRIPTION
  23 -----------
  24
  25 Use `git stash` when you want to record the current state of the
  26 working directory and the index, but want to go back to a clean
  27 working directory.  The command saves your local modifications away
  28 and reverts the working directory to match the `HEAD` commit.
  29
  30 The modifications stashed away by this command can be listed with
  31 `git stash list`, inspected with `git stash show`, and restored
  32 (potentially on top of a different commit) with `git stash apply`.
  33 Calling `git stash` without any arguments is equivalent to `git stash save`.
  34 A stash is by default listed as "WIP on 'branchname' ...", but
  35 you can give a more descriptive message on the command line when
  36 you create one.
  37
  38 The latest stash you created is stored in `refs/stash`; older
  39 stashes are found in the reflog of this reference and can be named using
  40 the usual reflog syntax (e.g. `stash@{0}` is the most recently
  41 created stash, `stash@{1}` is the one before it, `stash@{2.hours.ago}`
  42 is also possible). Stashes may also be referenced by specifying just the
  43 stash index (e.g. the integer `n` is equivalent to `stash@{n}`).
  44
  45 OPTIONS
  46 -------
  47
  48 save [-p|--patch] [-k|--[no-]keep-index] [-u|--include-untracked] [-a|--all] [-q|--quiet] [<message>]::
  49
  50         Save your local modifications to a new 'stash', and run `git reset
  51         --hard` to revert them.  The <message> part is optional and gives
  52         the description along with the stashed state.  For quickly making
  53         a snapshot, you can omit _both_ "save" and <message>, but giving
  54         only <message> does not trigger this action to prevent a misspelled
  55         subcommand from making an unwanted stash.
  56 +
  57 If the `--keep-index` option is used, all changes already added to the
  58 index are left intact.
  59 +
  60 If the `--include-untracked` option is used, all untracked files are also
  61 stashed and then cleaned up with `git clean`, leaving the working directory
  62 in a very clean state. If the `--all` option is used instead then the
  63 ignored files are stashed and cleaned in addition to the untracked files.
  64 +
  65 With `--patch`, you can interactively select hunks from the diff
  66 between HEAD and the working tree to be stashed.  The stash entry is
  67 constructed such that its index state is the same as the index state
  68 of your repository, and its worktree contains only the changes you
  69 selected interactively.  The selected changes are then rolled back
  70 from your worktree. See the ``Interactive Mode'' section of
  71 linkgit:git-add[1] to learn how to operate the `--patch` mode.
  72 +
  73 The `--patch` option implies `--keep-index`.  You can use
  74 `--no-keep-index` to override this.
  75
  76 list [<options>]::
  77
  78         List the stashes that you currently have.  Each 'stash' is listed
  79         with its name (e.g. `stash@{0}` is the latest stash, `stash@{1}` is
  80         the one before, etc.), the name of the branch that was current when the
  81         stash was made, and a short description of the commit the stash was
  82         based on.
  83 +
  84 ----------------------------------------------------------------
  85 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
  86 stash@{1}: On master: 9cc0589... Add git-stash
  87 ----------------------------------------------------------------
  88 +
  89 The command takes options applicable to the 'git log'
  90 command to control what is shown and how. See linkgit:git-log[1].
  91
  92 show [<stash>]::
  93
  94         Show the changes recorded in the stash as a diff between the
  95         stashed state and its original parent. When no `<stash>` is given,
  96         shows the latest one. By default, the command shows the diffstat, but
  97         it will accept any format known to 'git diff' (e.g., `git stash show
  98         -p stash@{1}` to view the second most recent stash in patch form).
  99         You can use stash.showStat and/or stash.showPatch config variables
 100         to change the default behavior.
 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 save`. 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 If the `--index` option is used, then tries to reinstate not only the working
 114 tree's changes, but also the index's ones. However, this can fail, when you
 115 have conflicts (which are stored in the index, where you therefore can no
 116 longer apply the changes as they were originally).
 117 +
 118 When no `<stash>` is given, `stash@{0}` is assumed, otherwise `<stash>` must
 119 be a reference of the form `stash@{<revision>}`.
 120
 121 apply [--index] [-q|--quiet] [<stash>]::
 122
 123         Like `pop`, but do not remove the state from the stash list. Unlike `pop`,
 124         `<stash>` may be any commit that looks like a commit created by
 125         `stash save` or `stash create`.
 126
 127 branch <branchname> [<stash>]::
 128
 129         Creates and checks out a new branch named `<branchname>` starting from
 130         the commit at which the `<stash>` was originally created, applies the
 131         changes recorded in `<stash>` to the new working tree and index.
 132         If that succeeds, and `<stash>` is a reference of the form
 133         `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>`
 134         is given, applies the latest one.
 135 +
 136 This is useful if the branch on which you ran `git stash save` has
 137 changed enough that `git stash apply` fails due to conflicts. Since
 138 the stash is applied on top of the commit that was HEAD at the time
 139 `git stash` was run, it restores the originally stashed state with
 140 no conflicts.
 141
 142 clear::
 143         Remove all the stashed states. Note that those states will then
 144         be subject to pruning, and may be impossible to recover (see
 145         'Examples' below for a possible strategy).
 146
 147 drop [-q|--quiet] [<stash>]::
 148
 149         Remove a single stashed state from the stash list. When no `<stash>`
 150         is given, it removes the latest one. i.e. `stash@{0}`, otherwise
 151         `<stash>` must be a valid stash log reference of the form
 152         `stash@{<revision>}`.
 153
 154 create::
 155
 156         Create a stash (which is a regular commit object) and return its
 157         object name, without storing it anywhere in the ref namespace.
 158         This is intended to be useful for scripts.  It is probably not
 159         the command you want to use; see "save" above.
 160
 161 store::
 162
 163         Store a given stash created via 'git stash create' (which is a
 164         dangling merge commit) in the stash ref, updating the stash
 165         reflog.  This is intended to be useful for scripts.  It is
 166         probably not the command you want to use; see "save" above.
 167
 168 DISCUSSION
 169 ----------
 170
 171 A stash is represented as a commit whose tree records the state of the
 172 working directory, and its first parent is the commit at `HEAD` when
 173 the stash was created.  The tree of the second parent records the
 174 state of the index when the stash is made, and it is made a child of
 175 the `HEAD` commit.  The ancestry graph looks like this:
 176
 177             .----W
 178            /    /
 179      -----H----I
 180
 181 where `H` is the `HEAD` commit, `I` is a commit that records the state
 182 of the index, and `W` is a commit that records the state of the working
 183 tree.
 184
 185
 186 EXAMPLES
 187 --------
 188
 189 Pulling into a dirty tree::
 190
 191 When you are in the middle of something, you learn that there are
 192 upstream changes that are possibly relevant to what you are
 193 doing.  When your local changes do not conflict with the changes in
 194 the upstream, a simple `git pull` will let you move forward.
 195 +
 196 However, there are cases in which your local changes do conflict with
 197 the upstream changes, and `git pull` refuses to overwrite your
 198 changes.  In such a case, you can stash your changes away,
 199 perform a pull, and then unstash, like this:
 200 +
 201 ----------------------------------------------------------------
 202 $ git pull
 203  ...
 204 file foobar not up to date, cannot merge.
 205 $ git stash
 206 $ git pull
 207 $ git stash pop
 208 ----------------------------------------------------------------
 209
 210 Interrupted workflow::
 211
 212 When you are in the middle of something, your boss comes in and
 213 demands that you fix something immediately.  Traditionally, you would
 214 make a commit to a temporary branch to store your changes away, and
 215 return to your original branch to make the emergency fix, like this:
 216 +
 217 ----------------------------------------------------------------
 218 # ... hack hack hack ...
 219 $ git checkout -b my_wip
 220 $ git commit -a -m "WIP"
 221 $ git checkout master
 222 $ edit emergency fix
 223 $ git commit -a -m "Fix in a hurry"
 224 $ git checkout my_wip
 225 $ git reset --soft HEAD^
 226 # ... continue hacking ...
 227 ----------------------------------------------------------------
 228 +
 229 You can use 'git stash' to simplify the above, like this:
 230 +
 231 ----------------------------------------------------------------
 232 # ... hack hack hack ...
 233 $ git stash
 234 $ edit emergency fix
 235 $ git commit -a -m "Fix in a hurry"
 236 $ git stash pop
 237 # ... continue hacking ...
 238 ----------------------------------------------------------------
 239
 240 Testing partial commits::
 241
 242 You can use `git stash save --keep-index` when you want to make two or
 243 more commits out of the changes in the work tree, and you want to test
 244 each change before committing:
 245 +
 246 ----------------------------------------------------------------
 247 # ... hack hack hack ...
 248 $ git add --patch foo            # add just first part to the index
 249 $ git stash save --keep-index    # save all other changes to the stash
 250 $ edit/build/test first part
 251 $ git commit -m 'First part'     # commit fully tested change
 252 $ git stash pop                  # prepare to work on all other changes
 253 # ... repeat above five steps until one commit remains ...
 254 $ edit/build/test remaining parts
 255 $ git commit foo -m 'Remaining parts'
 256 ----------------------------------------------------------------
 257
 258 Recovering stashes that were cleared/dropped erroneously::
 259
 260 If you mistakenly drop or clear stashes, they cannot be recovered
 261 through the normal safety mechanisms.  However, you can try the
 262 following incantation to get a list of stashes that are still in your
 263 repository, but not reachable any more:
 264 +
 265 ----------------------------------------------------------------
 266 git fsck --unreachable |
 267 grep commit | cut -d\  -f3 |
 268 xargs git log --merges --no-walk --grep=WIP
 269 ----------------------------------------------------------------
 270
 271
 272 SEE ALSO
 273 --------
 274 linkgit:git-checkout[1],
 275 linkgit:git-commit[1],
 276 linkgit:git-reflog[1],
 277 linkgit:git-reset[1]
 278
 279 GIT
 280 ---
 281 Part of the linkgit:git[1] suite