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