{"thread":{"id":"22919","subject":"[PATCH] Documentation: reset: describe new \"--keep\" option","startedAt":"2010-03-05T20:25:36Z","lastAt":"2010-03-08T11:31:51Z","messageCount":8,"participants":["Christian Couder","Peter Baumann","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"136221","messageId":"20100305202537.25469.73470.chriscool@tuxfamily.org","threadId":"22919","inReplyTo":null,"subject":"[PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2010-03-05T20:25:36Z","receivedAt":"2010-03-05T20:25:36Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"and give an example to show how it can be used.\n\nSigned-off-by: Christian Couder \nSigned-off-by: Junio C Hamano \n---\n Documentation/git-reset.txt | 49 ++++++++++++++++++++++++++++++++++++++++++-\n 1 files changed, 48 insertions(+), 1 deletions(-)\n\nThis patch replaces the patch with the same name currently in pu.\nThe example given at then end is much improved, thanks to Junio.\n\ndiff --git a/Documentation/git-reset.txt b/Documentation/git-reset.txt\nindex 168db08..1e9ae0a 100644\n--- a/Documentation/git-reset.txt\n+++ b/Documentation/git-reset.txt\n@@ -8,7 +8,7 @@ git-reset - Reset current HEAD to the specified state\n SYNOPSIS\n --------\n [verse]\n-'git reset' [--mixed | --soft | --hard | --merge] [-q] []\n+'git reset' [--mixed | --soft | --hard | --merge | --keep] [-q] []\n 'git reset' [-q] [] [--] ...\n 'git reset' --patch [] [--] [...]\n \n@@ -52,6 +52,11 @@ OPTIONS\n \tand updates the files that are different between the named commit\n \tand the current commit in the working tree.\n \n+--keep::\n+\tResets the index to match the tree recorded by the named commit,\n+\tbut keep changes in the working tree. Aborts if the reset would\n+\tchange files that are already modified in the working tree.\n+\n -p::\n --patch::\n \tInteractively select hunks in the difference between the index\n@@ -93,6 +98,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed A D D\n \t\t\t\t--hard D D D\n \t\t\t\t--merge (disallowed)\n+\t\t\t\t--keep (disallowed)\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -100,6 +106,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed A C C\n \t\t\t\t--hard C C C\n \t\t\t\t--merge (disallowed)\n+\t\t\t\t--keep A C C\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -107,6 +114,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed B D D\n \t\t\t\t--hard D D D\n \t\t\t\t--merge D D D\n+\t\t\t\t--keep (disallowed)\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -114,6 +122,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed B C C\n \t\t\t\t--hard C C C\n \t\t\t\t--merge C C C\n+\t\t\t\t--keep B C C\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -121,6 +130,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed B D D\n \t\t\t\t--hard D D D\n \t\t\t\t--merge (disallowed)\n+\t\t\t\t--keep (disallowed)\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -128,6 +138,7 @@ in the index and in state D in HEAD.\n \t\t\t\t--mixed B C C\n \t\t\t\t--hard C C C\n \t\t\t\t--merge B C C\n+\t\t\t\t--keep B C C\n \n \"reset --merge\" is meant to be used when resetting out of a conflicted\n merge. Any mergy operation guarantees that the work tree file that is\n@@ -138,6 +149,14 @@ between the index and the work tree, then it means that we are not\n resetting out from a state that a mergy operation left after failing\n with a conflict. That is why we disallow --merge option in this case.\n \n+\"reset --keep\" is meant to be used when removing some of the last\n+commits in the current branch while keeping changes in the working\n+tree. If there could be conflicts between the changes in the commit we\n+want to remove and the changes in the working tree we want to keep,\n+the reset is disallowed. That's why it is disallowed if there are both\n+changes between the working tree and HEAD, and between HEAD and the\n+target.\n+\n The following tables show what happens when there are unmerged\n entries:\n \n@@ -147,6 +166,7 @@ entries:\n \t\t\t\t--mixed X B B\n \t\t\t\t--hard B B B\n \t\t\t\t--merge B B B\n+\t\t\t\t--keep (disallowed)\n \n working index HEAD target working index HEAD\n ----------------------------------------------------\n@@ -154,6 +174,7 @@ entries:\n \t\t\t\t--mixed X A A\n \t\t\t\t--hard A A A\n \t\t\t\t--merge A A A\n+\t\t\t\t--keep X A A\n \n X means any state and U means an unmerged index.\n \n@@ -325,6 +346,32 @@ $ git add frotz.c <3>\n <2> This commits all other changes in the index.\n <3> Adds the file to the index again.\n \n+Keep changes in working tree while discarding some previous commits::\n++\n+Suppose you are working on something and you commit it, and then you\n+continue working a bit more, but now you think that what you have in\n+your working tree should be in another branch that has nothing to do\n+with what you commited previously. You can start a new branch and\n+reset it while keeping the changes in your work tree.\n++\n+------------\n+$ git tag start\n+$ git checkout -b branch1\n+$ edit\n+$ git commit ... <1>\n+$ edit\n+$ git checkout -b branch2 <2>\n+$ git reset --keep start <3>\n+------------\n++\n+<1> This commits your first edits in branch1.\n+<2> In the ideal world, you could have realized that the earlier\n+ commit did not belong to the new topic when you created and switched\n+ to branch2 (i.e. \"git checkout -b branch2 start\"), but nobody is\n+ perfect.\n+<3> But you can use \"reset --keep\" to remove the unwanted commit after\n+ you switched to \"branch2\".\n+\n Author\n ------\n Written by Junio C Hamano and Linus Torvalds \n-- \n1.7.0.1.335.g17865\n"},{"id":"136234","messageId":"20100306081034.GA4827@m62s10.vlinux.de","threadId":"22919","inReplyTo":"20100305202537.25469.73470.chriscool@tuxfamily.org","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Peter Baumann","fromEmail":"waste.manager@gmx.de","sentAt":"2010-03-06T08:10:34Z","receivedAt":"2010-03-06T08:10:34Z","isPatch":true,"sender":{"key":"waste.manager@gmx.de","avatar":null},"body":"On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:\n> and give an example to show how it can be used.\n> \n> +--keep::\n> +\tResets the index to match the tree recorded by the named commit,\n> +\tbut keep changes in the working tree. Aborts if the reset would\n> +\tchange files that are already modified in the working tree.\n> +\n \nHuh? Keep changes (by not touching the worktree) and then aborting if we\ntouch the worktree. Seems like a contradiction to me.\n\n--\nPeter\n"},{"id":"136330","messageId":"201003062026.11489.chriscool@tuxfamily.org","threadId":"22919","inReplyTo":"20100306081034.GA4827@m62s10.vlinux.de","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2010-03-06T19:26:11Z","receivedAt":"2010-03-06T19:26:11Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Saturday 06 March 2010 09:10:34 Peter Baumann wrote:\n> On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:\n> > and give an example to show how it can be used.\n> >\n> > +--keep::\n> > +\tResets the index to match the tree recorded by the named commit,\n> > +\tbut keep changes in the working tree. Aborts if the reset would\n> > +\tchange files that are already modified in the working tree.\n> > +\n> \n> Huh? Keep changes (by not touching the worktree)\n\nKeep uncommited changes in the working tree does not mean not touching the \nworking tree.\n\n> and then aborting if we\n> touch the worktree.\n\nWe abort if the commit we reset touch some files that have uncommited changes.\n\n> Seems like a contradiction to me.\n\nThere is no contradiction. We repeat \"working tree\" too much perhaps, but what \nis important is to focus on \"changes\" and \"files\".\n\nRegards,\nChristian.\n"},{"id":"136293","messageId":"7vaaukadap.fsf@alter.siamese.dyndns.org","threadId":"22919","inReplyTo":"20100305202537.25469.73470.chriscool@tuxfamily.org","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-07T05:52:46Z","receivedAt":"2010-03-07T05:52:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Christian Couder writes:\n\n> and give an example to show how it can be used.\n>\n> Signed-off-by: Christian Couder \n> Signed-off-by: Junio C Hamano \n> ---\n\nThanks. With the example I think I can tell others that this at least has\none known use case that is not totally whacky.\n\nI haven't re-read Peter Baumann's comments that you dismissed as a\nmis-reading of your added documentation, but if somebody _can_ misread\nwhat you wrote, that is a sign that it has a room to be improved for\nclarity.\n"},{"id":"136352","messageId":"201003072138.18583.chriscool@tuxfamily.org","threadId":"22919","inReplyTo":"7vaaukadap.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Christian Couder","fromEmail":"chriscool@tuxfamily.org","sentAt":"2010-03-07T20:38:18Z","receivedAt":"2010-03-07T20:38:18Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Sunday 07 March 2010 06:52:46 Junio C Hamano wrote:\n> Christian Couder writes:\n> > and give an example to show how it can be used.\n> >\n> > Signed-off-by: Christian Couder \n> > Signed-off-by: Junio C Hamano \n> > ---\n> \n> Thanks. With the example I think I can tell others that this at least has\n> one known use case that is not totally whacky.\n> \n> I haven't re-read Peter Baumann's comments that you dismissed as a\n> mis-reading of your added documentation, but if somebody _can_ misread\n> what you wrote, that is a sign that it has a room to be improved for\n> clarity.\n\nOk, so instead of:\n\n> +--keep::\n> + Resets the index to match the tree recorded by the named commit,\n> + but keep changes in the working tree. Aborts if the reset would\n> + change files that are already modified in the working tree.\n\nwhat about:\n\n--keep::\n Resets the index to match the tree recorded by the named commit,\n but changed files in the working tree are kept untouched. Aborts if the\n reset would touch any of them.\n\n?\n\nThanks,\nChristian.\n"},{"id":"136377","messageId":"7v3a0b1afe.fsf@alter.siamese.dyndns.org","threadId":"22919","inReplyTo":"20100306081034.GA4827@m62s10.vlinux.de","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-08T08:31:49Z","receivedAt":"2010-03-08T08:31:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Peter Baumann writes:\n\n> On Fri, Mar 05, 2010 at 09:25:36PM +0100, Christian Couder wrote:\n>> and give an example to show how it can be used.\n>> \n>> +--keep::\n>> +\tResets the index to match the tree recorded by the named commit,\n>> +\tbut keep changes in the working tree. Aborts if the reset would\n>> +\tchange files that are already modified in the working tree.\n>> +\n> \n> Huh? Keep changes (by not touching the worktree) and then aborting if we\n> touch the worktree. Seems like a contradiction to me.\n\nHere is my try...\n\n Reset the index to the given commit, keeping local changes in the working\n tree since the current commit, while updating working tree files without\n local changes to what appears in the given commit. If a file that is\n different between the current commit and the given commit has local\n changes, reset is aborted.\n"},{"id":"136379","messageId":"20100308084745.GB4827@m62s10.vlinux.de","threadId":"22919","inReplyTo":"201003072138.18583.chriscool@tuxfamily.org","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Peter Baumann","fromEmail":"waste.manager@gmx.de","sentAt":"2010-03-08T08:47:45Z","receivedAt":"2010-03-08T08:47:45Z","isPatch":true,"sender":{"key":"waste.manager@gmx.de","avatar":null},"body":"On Sun, Mar 07, 2010 at 09:38:18PM +0100, Christian Couder wrote:\n> On Sunday 07 March 2010 06:52:46 Junio C Hamano wrote:\n> > Christian Couder writes:\n> > > and give an example to show how it can be used.\n> > >\n> > > Signed-off-by: Christian Couder \n> > > Signed-off-by: Junio C Hamano \n> > > ---\n> > \n> > Thanks. With the example I think I can tell others that this at least has\n> > one known use case that is not totally whacky.\n> > \n> > I haven't re-read Peter Baumann's comments that you dismissed as a\n> > mis-reading of your added documentation, but if somebody _can_ misread\n> > what you wrote, that is a sign that it has a room to be improved for\n> > clarity.\n> \n> Ok, so instead of:\n> \n> > +--keep::\n> > + Resets the index to match the tree recorded by the named commit,\n> > + but keep changes in the working tree. Aborts if the reset would\n> > + change files that are already modified in the working tree.\n> \n> what about:\n> \n> --keep::\n> Resets the index to match the tree recorded by the named commit,\n\nMy reading of this (non native english speaker): Given the --keep flag,\n*only* the index is updated.\n\n> but changed files in the working tree are kept untouched. \n> Aborts if the reset would touch any of them.\n\nHuh? Does it touch the work tree, too? You propably know by now where this\nleads :-)\n\nI have to admit I like Junio's version better, because at least it is clear\nthat the worktree is also touched.\n\n--\nPeter\n"},{"id":"136385","messageId":"c07716ae1003080331j16cc29d5j6f6c1d7e940d03b8@mail.gmail.com","threadId":"22919","inReplyTo":"7v3a0b1afe.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: reset: describe new \"--keep\" option","fromName":"Christian Couder","fromEmail":"christian.couder@gmail.com","sentAt":"2010-03-08T11:31:51Z","receivedAt":"2010-03-08T11:31:51Z","isPatch":true,"sender":{"key":"christian.couder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/208954?v=4"},"body":"On Mon, Mar 8, 2010 at 9:31 AM, Junio C Hamano wrote:\n> Peter Baumann writes:\n>\n>> Huh? Keep changes (by not touching the worktree) and then aborting if we\n>> touch the worktree. Seems like a contradiction to me.\n>\n> Here is my try...\n>\n>    Reset the index to the given commit, keeping local changes in the working\n>    tree since the current commit, while updating working tree files without\n>    local changes to what appears in the given commit.  If a file that is\n>    different between the current commit and the given commit has local\n>    changes, reset is aborted.\n\nI agree that it is better. I will post a patch with this change this\nevening if you don't do it before.\n\nThanks,\nChristian.\n"}]}