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'
  12 'git-stash' [list | show [<stash>] | apply [<stash>] | clear]
  13
  14 DESCRIPTION
  15 -----------
  16
  17 Use 'git-stash' when you want to record the current state of the
  18 working directory and the index, but want to go back to a clean
  19 working directory.  The command saves your local modifications away
  20 and reverts the working directory to match the `HEAD` commit.
  21
  22 The modifications stashed away by this command can be listed with
  23 `git-stash list`, inspected with `git-stash show`, and restored
  24 (potentially on top of a different commit) with `git-stash apply`
  25 commands.  The default operation when called without options is to
  26 save the changes away.
  27
  28 The latest stash you created is stored in `$GIT_DIR/refs/stash`; older
  29 stashes are found in the reflog of this refererence and can be named using
  30 the usual reflog syntax (e.g. `stash@{1}` is the stash one previously made,
  31 `stash@{2}` is the one before it, `stash@{2.hours.ago}` is also possible).
  32
  33 OPTIONS
  34 -------
  35
  36 (no subcommand)::
  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), 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.  When no `<stash>` is given,
  57         shows the latest one.  By default, the command shows diffstat, but
  58         you can add `-p` option (i.e. `git stash show -p stash@{2}`) to view
  59         it in patch form.
  60
  61 apply [<stash>]::
  62
  63         Restores the changes recorded in the stash on top of the current
  64         working tree state.  When no `<stash>` is given, applies the latest
  65         one.  The working directory must match the index.  When the changes
  66         conflict, you need to resolve them by hand and mark the result with
  67         `git add` as usual.  When the changes are cleanly merged, your
  68         earlier local changes stored in the stash becomes the differences
  69         between the index and the working tree (i.e. `git diff`), except
  70         that newly created files are registered in the index (i.e. `git diff
  71         --cached` is necessary to review the newly added files).
  72
  73 clear::
  74         Removes all the stashed states.
  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 changes that possibly are relevant to what you are doing in the
 102 upstream.  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 first 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 you to fix something immediately.  Traditionally, you would
 123 make a commit to a temporary branch to store your changes away, and
 124 come back 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