mirrors/git
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation/reset: promote 'examples' one section up

Browse Source 
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:
Thomas Rast
2010-07-18 20:23:24 +02:00
committed by Junio C Hamano
parent 7b8cd49d5c
commit 28bb4b276a
1 changed files with 109 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
Documentation/git-reset.txt
View File

@ -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>