Skip to content

Commit

Permalink
Documentation/reset: promote 'examples' one section up
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
Thomas Rast authored and Junio C Hamano committed Jul 19, 2010
1 parent 7b8cd49 commit 28bb4b2
Showing 1 changed file with 109 additions and 107 deletions.
216 changes: 109 additions & 107 deletions Documentation/git-reset.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down Expand Up @@ -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>
Expand Down

0 comments on commit 28bb4b2

Please sign in to comment.