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