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' (save | list | show [<stash>] | apply [<stash>] | clear)
  12
  13 DESCRIPTION
  14 -----------
  15
  16 Use 'git-stash' when you want to record the current state of the
  17 working directory and the index, but want to go back to a clean
  18 working directory.  The command saves your local modifications away
  19 and reverts the working directory to match the `HEAD` commit.
  20
  21 The modifications stashed away by this command can be listed with
  22 `git-stash list`, inspected with `git-stash show`, and restored
  23 (potentially on top of a different commit) with `git-stash apply`.
  24 Calling git-stash without any arguments is equivalent to `git-stash
  25 save`.
  26
  27 The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
  28 stashes are found in the reflog of this reference and can be named using
  29 the usual reflog syntax (e.g. `stash@\{1}` is the most recently
  30 created stash, `stash@\{2}` is the one before it, `stash@\{2.hours.ago}`
  31 is also possible).
  32
  33 OPTIONS
  34 -------
  35
  36 save::
  37
  38         Save your local modifications to a new 'stash', and run `git-reset
  39         --hard` to revert them.  This is the default action when no
  40         subcommand is given.
  41
  42 list::
  43
  44         List the stashes that you currently have.  Each 'stash' is listed
  45         with its name (e.g. `stash@\{0}` is the latest stash, `stash@\{1} is
  46         the one before, etc.), the name of the branch that was current when the
  47         stash was made, and a short description of the commit the stash was
  48         based on.
  49 +
  50 ----------------------------------------------------------------
  51 stash@{0}: submit: 6ebd0e2... Add git-stash
  52 stash@{1}: master: 9cc0589... Merge branch 'master' of gfi
  53 ----------------------------------------------------------------
  54
  55 show [<stash>]::
  56
  57         Show the changes recorded in the stash as a diff between the the
  58         stashed state and its original parent. When no `<stash>` is given,
  59         shows the latest one. By default, the command shows the diffstat, but
  60         it will accept any format known to `git-diff` (e.g., `git-stash show
  61         -p stash@\{2}` to view the second most recent stash in patch form).
  62
  63 apply [<stash>]::
  64
  65         Restore the changes recorded in the stash on top of the current
  66         working tree state.  When no `<stash>` is given, applies the latest
  67         one.  The working directory must match the index.
  68 +
  69 This operation can fail with conflicts; you need to resolve them
  70 by hand in the working tree.
  71
  72 clear::
  73         Remove all the stashed states. Note that those states will then
  74         be subject to pruning, and may be difficult or impossible to recover.
  75
  76
  77 DISCUSSION
  78 ----------
  79
  80 A stash is represented as a commit whose tree records the state of the
  81 working directory, and its first parent is the commit at `HEAD` when
  82 the stash was created.  The tree of the second parent records the
  83 state of the index when the stash is made, and it is made a child of
  84 the `HEAD` commit.  The ancestry graph looks like this:
  85
  86             .----W
  87            /    /
  88      -----H----I
  89
  90 where `H` is the `HEAD` commit, `I` is a commit that records the state
  91 of the index, and `W` is a commit that records the state of the working
  92 tree.
  93
  94
  95 EXAMPLES
  96 --------
  97
  98 Pulling into a dirty tree::
  99
 100 When you are in the middle of something, you learn that there are
 101 upstream changes that are possibly relevant to what you are
 102 doing.  When your local changes do not conflict with the changes in
 103 the upstream, a simple `git pull` will let you move forward.
 104 +
 105 However, there are cases in which your local changes do conflict with
 106 the upstream changes, and `git pull` refuses to overwrite your
 107 changes.  In such a case, you can stash your changes away,
 108 perform a pull, and then unstash, like this:
 109 +
 110 ----------------------------------------------------------------
 111 $ git pull
 112 ...
 113 file foobar not up to date, cannot merge.
 114 $ git stash
 115 $ git pull
 116 $ git stash apply
 117 ----------------------------------------------------------------
 118
 119 Interrupted workflow::
 120
 121 When you are in the middle of something, your boss comes in and
 122 demands that you fix something immediately.  Traditionally, you would
 123 make a commit to a temporary branch to store your changes away, and
 124 return to your original branch to make the emergency fix, like this:
 125 +
 126 ----------------------------------------------------------------
 127 ... hack hack hack ...
 128 $ git checkout -b my_wip
 129 $ git commit -a -m "WIP"
 130 $ git checkout master
 131 $ edit emergency fix
 132 $ git commit -a -m "Fix in a hurry"
 133 $ git checkout my_wip
 134 $ git reset --soft HEAD^
 135 ... continue hacking ...
 136 ----------------------------------------------------------------
 137 +
 138 You can use `git-stash` to simplify the above, like this:
 139 +
 140 ----------------------------------------------------------------
 141 ... hack hack hack ...
 142 $ git stash
 143 $ edit emergency fix
 144 $ git commit -a -m "Fix in a hurry"
 145 $ git stash apply
 146 ... continue hacking ...
 147 ----------------------------------------------------------------
 148
 149 SEE ALSO
 150 --------
 151 gitlink:git-checkout[1],
 152 gitlink:git-commit[1],
 153 gitlink:git-reflog[1],
 154 gitlink:git-reset[1]
 155
 156 AUTHOR
 157 ------
 158 Written by Nanako Shiraishi <nanako3@bluebottle.com>
 159
 160 GIT
 161 ---
 162 Part of the gitlink:git[7] suite