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 [<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 list [<options>]::
  50
  51         List the stashes that you currently have.  Each 'stash' is listed
  52         with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1}` is
  53         the one before, etc.), the name of the branch that was current when the
  54         stash was made, and a short description of the commit the stash was
  55         based on.
  56 +
  57 ----------------------------------------------------------------
  58 stash@{0}: WIP on submit: 6ebd0e2... Update git-stash documentation
  59 stash@{1}: On master: 9cc0589... Add git-stash
  60 ----------------------------------------------------------------
  61 +
  62 The command takes options applicable to the `git-log`
  63 command to control what is shown and how. See linkgit:git-log[1].
  64
  65 show [<stash>]::
  66
  67         Show the changes recorded in the stash as a diff between the
  68         stashed state and its original parent. When no `<stash>` is given,
  69         shows the latest one. By default, the command shows the diffstat, but
  70         it will accept any format known to `git-diff` (e.g., `git stash show
  71         -p stash@\{1}` to view the second most recent stash in patch form).
  72
  73 apply [--index] [<stash>]::
  74
  75         Restore the changes recorded in the stash on top of the current
  76         working tree state.  When no `<stash>` is given, applies the latest
  77         one.  The working directory must match the index.
  78 +
  79 This operation can fail with conflicts; you need to resolve them
  80 by hand in the working tree.
  81 +
  82 If the `--index` option is used, then tries to reinstate not only the working
  83 tree's changes, but also the index's ones. However, this can fail, when you
  84 have conflicts (which are stored in the index, where you therefore can no
  85 longer apply the changes as they were originally).
  86
  87 branch <branchname> [<stash>]::
  88
  89         Creates and checks out a new branch named `<branchname>` starting from
  90         the commit at which the `<stash>` was originally created, applies the
  91         changes recorded in `<stash>` to the new working tree and index, then
  92         drops the `<stash>` if that completes successfully. When no `<stash>`
  93         is given, applies the latest one.
  94 +
  95 This is useful if the branch on which you ran `git stash save` has
  96 changed enough that `git stash apply` fails due to conflicts. Since
  97 the stash is applied on top of the commit that was HEAD at the time
  98 `git stash` was run, it restores the originally stashed state with
  99 no conflicts.
 100
 101 clear::
 102         Remove all the stashed states. Note that those states will then
 103         be subject to pruning, and may be difficult or impossible to recover.
 104
 105 drop [<stash>]::
 106
 107         Remove a single stashed state from the stash list. When no `<stash>`
 108         is given, it removes the latest one. i.e. `stash@\{0}`
 109
 110 pop [<stash>]::
 111
 112         Remove a single stashed state from the stash list and apply on top
 113         of the current working tree state. When no `<stash>` is given,
 114         `stash@\{0}` is assumed. See also `apply`.
 115
 116
 117 DISCUSSION
 118 ----------
 119
 120 A stash is represented as a commit whose tree records the state of the
 121 working directory, and its first parent is the commit at `HEAD` when
 122 the stash was created.  The tree of the second parent records the
 123 state of the index when the stash is made, and it is made a child of
 124 the `HEAD` commit.  The ancestry graph looks like this:
 125
 126             .----W
 127            /    /
 128      -----H----I
 129
 130 where `H` is the `HEAD` commit, `I` is a commit that records the state
 131 of the index, and `W` is a commit that records the state of the working
 132 tree.
 133
 134
 135 EXAMPLES
 136 --------
 137
 138 Pulling into a dirty tree::
 139
 140 When you are in the middle of something, you learn that there are
 141 upstream changes that are possibly relevant to what you are
 142 doing.  When your local changes do not conflict with the changes in
 143 the upstream, a simple `git pull` will let you move forward.
 144 +
 145 However, there are cases in which your local changes do conflict with
 146 the upstream changes, and `git pull` refuses to overwrite your
 147 changes.  In such a case, you can stash your changes away,
 148 perform a pull, and then unstash, like this:
 149 +
 150 ----------------------------------------------------------------
 151 $ git pull
 152 ...
 153 file foobar not up to date, cannot merge.
 154 $ git stash
 155 $ git pull
 156 $ git stash apply
 157 ----------------------------------------------------------------
 158
 159 Interrupted workflow::
 160
 161 When you are in the middle of something, your boss comes in and
 162 demands that you fix something immediately.  Traditionally, you would
 163 make a commit to a temporary branch to store your changes away, and
 164 return to your original branch to make the emergency fix, like this:
 165 +
 166 ----------------------------------------------------------------
 167 ... hack hack hack ...
 168 $ git checkout -b my_wip
 169 $ git commit -a -m "WIP"
 170 $ git checkout master
 171 $ edit emergency fix
 172 $ git commit -a -m "Fix in a hurry"
 173 $ git checkout my_wip
 174 $ git reset --soft HEAD^
 175 ... continue hacking ...
 176 ----------------------------------------------------------------
 177 +
 178 You can use `git-stash` to simplify the above, like this:
 179 +
 180 ----------------------------------------------------------------
 181 ... hack hack hack ...
 182 $ git stash
 183 $ edit emergency fix
 184 $ git commit -a -m "Fix in a hurry"
 185 $ git stash apply
 186 ... continue hacking ...
 187 ----------------------------------------------------------------
 188
 189 SEE ALSO
 190 --------
 191 linkgit:git-checkout[1],
 192 linkgit:git-commit[1],
 193 linkgit:git-reflog[1],
 194 linkgit:git-reset[1]
 195
 196 AUTHOR
 197 ------
 198 Written by Nanako Shiraishi <nanako3@bluebottle.com>
 199
 200 GIT
 201 ---
 202 Part of the linkgit:git[1] suite