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>
This commit is contained in:
parent
7b8cd49d5c
commit
28bb4b276a
@ -83,113 +83,7 @@ OPTIONS
|
||||
Be quiet, only report errors.
|
||||
|
||||
|
||||
DISCUSSION
|
||||
----------
|
||||
|
||||
The tables below show what happens when running:
|
||||
|
||||
----------
|
||||
git reset --option target
|
||||
----------
|
||||
|
||||
to reset the HEAD to another commit (`target`) with the different
|
||||
reset options depending on the state of the files.
|
||||
|
||||
In these tables, A, B, C and D are some different states of a
|
||||
file. For example, the first line of the first table means that if a
|
||||
file is in state A in the working tree, in state B in the index, in
|
||||
state C in HEAD and in state D in the target, then "git reset --soft
|
||||
target" will put the file in state A in the working tree, in state B
|
||||
in the index and in state D in HEAD.
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
A B C D --soft A B D
|
||||
--mixed A D D
|
||||
--hard D D D
|
||||
--merge (disallowed)
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
A B C C --soft A B C
|
||||
--mixed A C C
|
||||
--hard C C C
|
||||
--merge (disallowed)
|
||||
--keep A C C
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B B C D --soft B B D
|
||||
--mixed B D D
|
||||
--hard D D D
|
||||
--merge D D D
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B B C C --soft B B C
|
||||
--mixed B C C
|
||||
--hard C C C
|
||||
--merge C C C
|
||||
--keep B C C
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B C C D --soft B C D
|
||||
--mixed B D D
|
||||
--hard D D D
|
||||
--merge (disallowed)
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B C C C --soft B C C
|
||||
--mixed B C C
|
||||
--hard C C C
|
||||
--merge B C C
|
||||
--keep B C C
|
||||
|
||||
"reset --merge" is meant to be used when resetting out of a conflicted
|
||||
merge. Any mergy operation guarantees that the work tree file that is
|
||||
involved in the merge does not have local change wrt the index before
|
||||
it starts, and that it writes the result out to the work tree. So if
|
||||
we see some difference between the index and the target and also
|
||||
between the index and the work tree, then it means that we are not
|
||||
resetting out from a state that a mergy operation left after failing
|
||||
with a conflict. That is why we disallow --merge option in this case.
|
||||
|
||||
"reset --keep" is meant to be used when removing some of the last
|
||||
commits in the current branch while keeping changes in the working
|
||||
tree. If there could be conflicts between the changes in the commit we
|
||||
want to remove and the changes in the working tree we want to keep,
|
||||
the reset is disallowed. That's why it is disallowed if there are both
|
||||
changes between the working tree and HEAD, and between HEAD and the
|
||||
target. To be safe, it is also disallowed when there are unmerged
|
||||
entries.
|
||||
|
||||
The following tables show what happens when there are unmerged
|
||||
entries:
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
X U A B --soft (disallowed)
|
||||
--mixed X B B
|
||||
--hard B B B
|
||||
--merge B B B
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
X U A A --soft (disallowed)
|
||||
--mixed X A A
|
||||
--hard A A A
|
||||
--merge A A A
|
||||
--keep (disallowed)
|
||||
|
||||
X means any state and U means an unmerged index.
|
||||
|
||||
Examples
|
||||
EXAMPLES
|
||||
--------
|
||||
|
||||
Undo a commit and redo::
|
||||
@ -383,6 +277,114 @@ $ git reset --keep start <3>
|
||||
<3> But you can use "reset --keep" to remove the unwanted commit after
|
||||
you switched to "branch2".
|
||||
|
||||
|
||||
DISCUSSION
|
||||
----------
|
||||
|
||||
The tables below show what happens when running:
|
||||
|
||||
----------
|
||||
git reset --option target
|
||||
----------
|
||||
|
||||
to reset the HEAD to another commit (`target`) with the different
|
||||
reset options depending on the state of the files.
|
||||
|
||||
In these tables, A, B, C and D are some different states of a
|
||||
file. For example, the first line of the first table means that if a
|
||||
file is in state A in the working tree, in state B in the index, in
|
||||
state C in HEAD and in state D in the target, then "git reset --soft
|
||||
target" will put the file in state A in the working tree, in state B
|
||||
in the index and in state D in HEAD.
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
A B C D --soft A B D
|
||||
--mixed A D D
|
||||
--hard D D D
|
||||
--merge (disallowed)
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
A B C C --soft A B C
|
||||
--mixed A C C
|
||||
--hard C C C
|
||||
--merge (disallowed)
|
||||
--keep A C C
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B B C D --soft B B D
|
||||
--mixed B D D
|
||||
--hard D D D
|
||||
--merge D D D
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B B C C --soft B B C
|
||||
--mixed B C C
|
||||
--hard C C C
|
||||
--merge C C C
|
||||
--keep B C C
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B C C D --soft B C D
|
||||
--mixed B D D
|
||||
--hard D D D
|
||||
--merge (disallowed)
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
B C C C --soft B C C
|
||||
--mixed B C C
|
||||
--hard C C C
|
||||
--merge B C C
|
||||
--keep B C C
|
||||
|
||||
"reset --merge" is meant to be used when resetting out of a conflicted
|
||||
merge. Any mergy operation guarantees that the work tree file that is
|
||||
involved in the merge does not have local change wrt the index before
|
||||
it starts, and that it writes the result out to the work tree. So if
|
||||
we see some difference between the index and the target and also
|
||||
between the index and the work tree, then it means that we are not
|
||||
resetting out from a state that a mergy operation left after failing
|
||||
with a conflict. That is why we disallow --merge option in this case.
|
||||
|
||||
"reset --keep" is meant to be used when removing some of the last
|
||||
commits in the current branch while keeping changes in the working
|
||||
tree. If there could be conflicts between the changes in the commit we
|
||||
want to remove and the changes in the working tree we want to keep,
|
||||
the reset is disallowed. That's why it is disallowed if there are both
|
||||
changes between the working tree and HEAD, and between HEAD and the
|
||||
target. To be safe, it is also disallowed when there are unmerged
|
||||
entries.
|
||||
|
||||
The following tables show what happens when there are unmerged
|
||||
entries:
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
X U A B --soft (disallowed)
|
||||
--mixed X B B
|
||||
--hard B B B
|
||||
--merge B B B
|
||||
--keep (disallowed)
|
||||
|
||||
working index HEAD target working index HEAD
|
||||
----------------------------------------------------
|
||||
X U A A --soft (disallowed)
|
||||
--mixed X A A
|
||||
--hard A A A
|
||||
--merge A A A
|
||||
--keep (disallowed)
|
||||
|
||||
X means any state and U means an unmerged index.
|
||||
|
||||
|
||||
Author
|
||||
------
|
||||
Written by Junio C Hamano <gitster@pobox.com> and Linus Torvalds <torvalds@osdl.org>
|
||||
|
Loading…
Reference in New Issue
Block a user