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