Document git-stash
This describes the git-stash command. I borrowed a few paragraphs from Johannes's version, and added a few examples. Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
しらいしななこ committed
Jul 1, 2007 at 14:26 UTC
09ccdb630517842e6ad3d9354fbd856174c70d17
2 files changed
+163
Documentation/cmd-list.perl
+1
@@ -178,6 +178,7 @@ git-show-ref plumbinginterrogators
178
git-sh-setup purehelpers
179
git-ssh-fetch synchingrepositories
180
git-ssh-upload synchingrepositories
181
+git-stash mainporcelain
182
git-status mainporcelain
183
git-stripspace purehelpers
184
git-submodule mainporcelain
Documentation/git-stash.txt
new
+162
@@ -0,0 +1,162 @@
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