Documentation/reset: promote 'examples' one section up
Move the examples section upwards, before the discussion that gives the gory details. Adjust the style of the heading accordingly. Signed-off-by: Thomas Rast <trast@student.ethz.ch> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Thomas Rast committed
Jul 18, 2010 at 20:23 UTC
28bb4b276af31af07163b28cd790b51f7c15c4b6
1 file changed
+109
-107
Documentation/git-reset.txt
+109
-107
@@ -83,113 +83,7 @@ OPTIONS
83
Be quiet, only report errors.
84
85
86
-DISCUSSION
87
-----------
88
-
89
-The tables below show what happens when running:
90
-
91
-----------
92
-git reset --option target
93
-----------
94
-
95
-to reset the HEAD to another commit (`target`) with the different
96
-reset options depending on the state of the files.
97
-
98
-In these tables, A, B, C and D are some different states of a
99
-file. For example, the first line of the first table means that if a
100
-file is in state A in the working tree, in state B in the index, in
101
-state C in HEAD and in state D in the target, then "git reset --soft
102
-target" will put the file in state A in the working tree, in state B
103
-in the index and in state D in HEAD.
104
-
105
- working index HEAD target working index HEAD
106
- ----------------------------------------------------
107
- A B C D --soft A B D
108
- --mixed A D D
109
- --hard D D D
110
- --merge (disallowed)
111
- --keep (disallowed)
112
-
113
- working index HEAD target working index HEAD
114
- ----------------------------------------------------
115
- A B C C --soft A B C
116
- --mixed A C C
117
- --hard C C C
118
- --merge (disallowed)
119
- --keep A C C
120
-
121
- working index HEAD target working index HEAD
122
- ----------------------------------------------------
123
- B B C D --soft B B D
124
- --mixed B D D
125
- --hard D D D
126
- --merge D D D
127
- --keep (disallowed)
128
-
129
- working index HEAD target working index HEAD
130
- ----------------------------------------------------
131
- B B C C --soft B B C
132
- --mixed B C C
133
- --hard C C C
134
- --merge C C C
135
- --keep B C C
136
-
137
- working index HEAD target working index HEAD
138
- ----------------------------------------------------
139
- B C C D --soft B C D
140
- --mixed B D D
141
- --hard D D D
142
- --merge (disallowed)
143
- --keep (disallowed)
144
-
145
- working index HEAD target working index HEAD
146
- ----------------------------------------------------
147
- B C C C --soft B C C
148
- --mixed B C C
149
- --hard C C C
150
- --merge B C C
151
- --keep B C C
152
-
153
-"reset --merge" is meant to be used when resetting out of a conflicted
154
-merge. Any mergy operation guarantees that the work tree file that is
155
-involved in the merge does not have local change wrt the index before
156
-it starts, and that it writes the result out to the work tree. So if
157
-we see some difference between the index and the target and also
158
-between the index and the work tree, then it means that we are not
159
-resetting out from a state that a mergy operation left after failing
160
-with a conflict. That is why we disallow --merge option in this case.
161
-
162
-"reset --keep" is meant to be used when removing some of the last
163
-commits in the current branch while keeping changes in the working
164
-tree. If there could be conflicts between the changes in the commit we
165
-want to remove and the changes in the working tree we want to keep,
166
-the reset is disallowed. That's why it is disallowed if there are both
167
-changes between the working tree and HEAD, and between HEAD and the
168
-target. To be safe, it is also disallowed when there are unmerged
169
-entries.
170
-
171
-The following tables show what happens when there are unmerged
172
-entries:
173
-
174
- working index HEAD target working index HEAD
175
- ----------------------------------------------------
176
- X U A B --soft (disallowed)
177
- --mixed X B B
178
- --hard B B B
179
- --merge B B B
180
- --keep (disallowed)
181
-
182
- working index HEAD target working index HEAD
183
- ----------------------------------------------------
184
- X U A A --soft (disallowed)
185
- --mixed X A A
186
- --hard A A A
187
- --merge A A A
188
- --keep (disallowed)
189
-
190
-X means any state and U means an unmerged index.
191
-
192
-Examples
86
+EXAMPLES
87
--------
88
89
Undo a commit and redo::
@@ -383,6 +277,114 @@ $ git reset --keep start <3>
277
<3> But you can use "reset --keep" to remove the unwanted commit after
278
you switched to "branch2".
279
280
+
281
+DISCUSSION
282
+----------
283
+
284
+The tables below show what happens when running:
285
+
286
+----------
287
+git reset --option target
288
+----------
289
+
290
+to reset the HEAD to another commit (`target`) with the different
291
+reset options depending on the state of the files.
292
+
293
+In these tables, A, B, C and D are some different states of a
294
+file. For example, the first line of the first table means that if a
295
+file is in state A in the working tree, in state B in the index, in
296
+state C in HEAD and in state D in the target, then "git reset --soft
297
+target" will put the file in state A in the working tree, in state B
298
+in the index and in state D in HEAD.
299
+
300
+ working index HEAD target working index HEAD
301
+ ----------------------------------------------------
302
+ A B C D --soft A B D
303
+ --mixed A D D
304
+ --hard D D D
305
+ --merge (disallowed)
306
+ --keep (disallowed)
307
+
308
+ working index HEAD target working index HEAD
309
+ ----------------------------------------------------
310
+ A B C C --soft A B C
311
+ --mixed A C C
312
+ --hard C C C
313
+ --merge (disallowed)
314
+ --keep A C C
315
+
316
+ working index HEAD target working index HEAD
317
+ ----------------------------------------------------
318
+ B B C D --soft B B D
319
+ --mixed B D D
320
+ --hard D D D
321
+ --merge D D D
322
+ --keep (disallowed)
323
+
324
+ working index HEAD target working index HEAD
325
+ ----------------------------------------------------
326
+ B B C C --soft B B C
327
+ --mixed B C C
328
+ --hard C C C
329
+ --merge C C C
330
+ --keep B C C
331
+
332
+ working index HEAD target working index HEAD
333
+ ----------------------------------------------------
334
+ B C C D --soft B C D
335
+ --mixed B D D
336
+ --hard D D D
337
+ --merge (disallowed)
338
+ --keep (disallowed)
339
+
340
+ working index HEAD target working index HEAD
341
+ ----------------------------------------------------
342
+ B C C C --soft B C C
343
+ --mixed B C C
344
+ --hard C C C
345
+ --merge B C C
346
+ --keep B C C
347
+
348
+"reset --merge" is meant to be used when resetting out of a conflicted
349
+merge. Any mergy operation guarantees that the work tree file that is
350
+involved in the merge does not have local change wrt the index before
351
+it starts, and that it writes the result out to the work tree. So if
352
+we see some difference between the index and the target and also
353
+between the index and the work tree, then it means that we are not
354
+resetting out from a state that a mergy operation left after failing
355
+with a conflict. That is why we disallow --merge option in this case.
356
+
357
+"reset --keep" is meant to be used when removing some of the last
358
+commits in the current branch while keeping changes in the working
359
+tree. If there could be conflicts between the changes in the commit we
360
+want to remove and the changes in the working tree we want to keep,
361
+the reset is disallowed. That's why it is disallowed if there are both
362
+changes between the working tree and HEAD, and between HEAD and the
363
+target. To be safe, it is also disallowed when there are unmerged
364
+entries.
365
+
366
+The following tables show what happens when there are unmerged
367
+entries:
368
+
369
+ working index HEAD target working index HEAD
370
+ ----------------------------------------------------
371
+ X U A B --soft (disallowed)
372
+ --mixed X B B
373
+ --hard B B B
374
+ --merge B B B
375
+ --keep (disallowed)
376
+
377
+ working index HEAD target working index HEAD
378
+ ----------------------------------------------------
379
+ X U A A --soft (disallowed)
380
+ --mixed X A A
381
+ --hard A A A
382
+ --merge A A A
383
+ --keep (disallowed)
384
+
385
+X means any state and U means an unmerged index.
386
+
387
+
388
Author
389
------
390
Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org>