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