Documentation: teach stash/pop workflow instead of stash/apply
Recent discussion on the list showed some comments in favour of a stash/pop workflow: http://marc.info/?l=git&m=124234911423358&w=2 http://marc.info/?l=git&m=124235348327711&w=2 Change the stash documentation and examples to document pop in its own right (and apply in terms of pop), and use stash/pop in the examples. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
May 28, 2009 at 11:40 UTC
7b8988e113b44b9a2d806dde6161c133750c14e5
2 files changed
+18
-16
Documentation/git-stash.txt
+16
-14
@@ -75,14 +75,22 @@ show [<stash>]::
75
it will accept any format known to 'git-diff' (e.g., `git stash show
76
-p stash@\{1}` to view the second most recent stash in patch form).
77
78
-apply [--index] [<stash>]::
78
+pop [<stash>]::
79
80
- Restore the changes recorded in the stash on top of the current
81
- working tree state. When no `<stash>` is given, applies the latest
82
- one. The working directory must match the index.
80
+ Remove a single stashed state from the stash list and apply it
81
+ on top of the current working tree state, i.e., do the inverse
82
+ operation of `git stash save`. The working directory must
83
+ match the index.
84
+
84
-This operation can fail with conflicts; you need to resolve them
85
-by hand in the working tree.
85
+Applying the state can fail with conflicts; in this case, it is not
86
+removed from the stash list. You need to resolve the conflicts by hand
87
+and call `git stash drop` manually afterwards.
88
++
89
+When no `<stash>` is given, `stash@\{0}` is assumed. See also `apply`.
90
+
91
+apply [--index] [<stash>]::
92
+
93
+ Like `pop`, but do not remove the state from the stash list.
94
+
95
If the `--index` option is used, then tries to reinstate not only the working
96
tree's changes, but also the index's ones. However, this can fail, when you
@@ -112,12 +120,6 @@ drop [<stash>]::
120
Remove a single stashed state from the stash list. When no `<stash>`
121
is given, it removes the latest one. i.e. `stash@\{0}`
122
115
-pop [<stash>]::
116
-
117
- Remove a single stashed state from the stash list and apply on top
118
- of the current working tree state. When no `<stash>` is given,
119
- `stash@\{0}` is assumed. See also `apply`.
120
-
123
create::
124
125
Create a stash (which is a regular commit object) and return its
@@ -163,7 +165,7 @@ $ git pull
165
file foobar not up to date, cannot merge.
166
$ git stash
167
$ git pull
166
-$ git stash apply
168
+$ git stash pop
169
----------------------------------------------------------------
170
171
Interrupted workflow::
@@ -192,7 +194,7 @@ You can use 'git-stash' to simplify the above, like this:
194
$ git stash
195
$ edit emergency fix
196
$ git commit -a -m "Fix in a hurry"
195
-$ git stash apply
197
+$ git stash pop
198
# ... continue hacking ...
199
----------------------------------------------------------------
200
Documentation/user-manual.txt
+2
-2
@@ -1520,10 +1520,10 @@ $ git commit -a -m "blorpl: typofix"
1520
------------------------------------------------
1521
1522
After that, you can go back to what you were working on with
1523
-`git stash apply`:
1523
+`git stash pop`:
1524
1525
------------------------------------------------
1526
-$ git stash apply
1526
+$ git stash pop
1527
------------------------------------------------
1528
1529