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