Documentation: reset: describe new "--keep" option
and give an example to show how it can be used. Signed-off-by: Christian Couder <chriscool@tuxfamily.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Christian Couder committed
Mar 5, 2010 at 21:25 UTC
7349df1142a8dba579c015b51805cc290fcb4e6e
1 file changed
+48
-1
Documentation/git-reset.txt
+48
-1
@@ -8,7 +8,7 @@ git-reset - Reset current HEAD to the specified state
8
SYNOPSIS
9
--------
10
[verse]
11
-'git reset' [--mixed | --soft | --hard | --merge] [-q] [<commit>]
11
+'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] [<commit>]
12
'git reset' [-q] [<commit>] [--] <paths>...
13
'git reset' --patch [<commit>] [--] [<paths>...]
14
@@ -52,6 +52,11 @@ OPTIONS
52
and updates the files that are different between the named commit
53
and the current commit in the working tree.
54
55
+--keep::
56
+ Resets the index to match the tree recorded by the named commit,
57
+ but keep changes in the working tree. Aborts if the reset would
58
+ change files that are already modified in the working tree.
59
+
60
-p::
61
--patch::
62
Interactively select hunks in the difference between the index
@@ -93,6 +98,7 @@ in the index and in state D in HEAD.
98
--mixed A D D
99
--hard D D D
100
--merge (disallowed)
101
+ --keep (disallowed)
102
103
working index HEAD target working index HEAD
104
----------------------------------------------------
@@ -100,6 +106,7 @@ in the index and in state D in HEAD.
106
--mixed A C C
107
--hard C C C
108
--merge (disallowed)
109
+ --keep A C C
110
111
working index HEAD target working index HEAD
112
----------------------------------------------------
@@ -107,6 +114,7 @@ in the index and in state D in HEAD.
114
--mixed B D D
115
--hard D D D
116
--merge D D D
117
+ --keep (disallowed)
118
119
working index HEAD target working index HEAD
120
----------------------------------------------------
@@ -114,6 +122,7 @@ in the index and in state D in HEAD.
122
--mixed B C C
123
--hard C C C
124
--merge C C C
125
+ --keep B C C
126
127
working index HEAD target working index HEAD
128
----------------------------------------------------
@@ -121,6 +130,7 @@ in the index and in state D in HEAD.
130
--mixed B D D
131
--hard D D D
132
--merge (disallowed)
133
+ --keep (disallowed)
134
135
working index HEAD target working index HEAD
136
----------------------------------------------------
@@ -128,6 +138,7 @@ in the index and in state D in HEAD.
138
--mixed B C C
139
--hard C C C
140
--merge B C C
141
+ --keep B C C
142
143
"reset --merge" is meant to be used when resetting out of a conflicted
144
merge. Any mergy operation guarantees that the work tree file that is
@@ -138,6 +149,14 @@ between the index and the work tree, then it means that we are not
149
resetting out from a state that a mergy operation left after failing
150
with a conflict. That is why we disallow --merge option in this case.
151
152
+"reset --keep" is meant to be used when removing some of the last
153
+commits in the current branch while keeping changes in the working
154
+tree. If there could be conflicts between the changes in the commit we
155
+want to remove and the changes in the working tree we want to keep,
156
+the reset is disallowed. That's why it is disallowed if there are both
157
+changes between the working tree and HEAD, and between HEAD and the
158
+target.
159
+
160
The following tables show what happens when there are unmerged
161
entries:
162
@@ -147,6 +166,7 @@ entries:
166
--mixed X B B
167
--hard B B B
168
--merge B B B
169
+ --keep (disallowed)
170
171
working index HEAD target working index HEAD
172
----------------------------------------------------
@@ -154,6 +174,7 @@ entries:
174
--mixed X A A
175
--hard A A A
176
--merge A A A
177
+ --keep X A A
178
179
X means any state and U means an unmerged index.
180
@@ -325,6 +346,32 @@ $ git add frotz.c <3>
346
<2> This commits all other changes in the index.
347
<3> Adds the file to the index again.
348
349
+Keep changes in working tree while discarding some previous commits::
350
++
351
+Suppose you are working on something and you commit it, and then you
352
+continue working a bit more, but now you think that what you have in
353
+your working tree should be in another branch that has nothing to do
354
+with what you commited previously. You can start a new branch and
355
+reset it while keeping the changes in your work tree.
356
++
357
+------------
358
+$ git tag start
359
+$ git checkout -b branch1
360
+$ edit
361
+$ git commit ... <1>
362
+$ edit
363
+$ git checkout -b branch2 <2>
364
+$ git reset --keep start <3>
365
+------------
366
++
367
+<1> This commits your first edits in branch1.
368
+<2> In the ideal world, you could have realized that the earlier
369
+ commit did not belong to the new topic when you created and switched
370
+ to branch2 (i.e. "git checkout -b branch2 start"), but nobody is
371
+ perfect.
372
+<3> But you can use "reset --keep" to remove the unwanted commit after
373
+ you switched to "branch2".
374
+
375
Author
376
------
377
Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org>