{"thread":{"id":"15088","subject":"[PATCH] Add hints to revert documentation about other ways to undo changes","startedAt":"2008-08-19T17:06:47Z","lastAt":"2008-08-20T23:52:49Z","messageCount":6,"participants":["Tarmigan","Junio C Hamano","Tarmigan Casebolt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"87714","messageId":"905315640808191006y6defa44fu2fdd41c034ffc263@mail.gmail.com","threadId":"15088","inReplyTo":"1219165591-19969-1-git-send-email-tarmigan+git@gmail.com","subject":"[PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Tarmigan","fromEmail":"tarmigan+git@gmail.com","sentAt":"2008-08-19T17:06:47Z","receivedAt":"2008-08-19T17:06:47Z","isPatch":true,"sender":{"key":"tarmigan+git@gmail.com","avatar":null},"body":"[Resending to git list. Original was rejected by vger with\nMessage headers can not have 8-bit non-ASCII characters in it; Use\nMIME encodings if such are needed!\nso trying to mail list directly for discussion. This copy is probably\nmangled in the forward.]\n\nFrom: Tarmigan Casebolt \nDate: Tue, Aug 19, 2008 at 10:06 AM\nSubject: [PATCH] Add hints to revert documentation about other ways to\nundo changes\nTo: gitster@pobox.com\n\nBased on its name, people may read the 'git revert' documentation when\nthey want to undo local changes, especially people who have used other\nSCM's. 'git revert' may not be what they had in mind, but git\nprovides several other ways to undo changes to files. We can help\nthem by pointing them towards the git commands that do what they might\nwant to do.\n\nCc: Daniel Barkalow \nCc: \"Peter Valdemar Mørch (Lists)\" <4ux6as402@sneakemail.com>\nCc: Lea Wiemann \nSigned-off-by: Tarmigan Casebolt \n---\n\nI put this in a Note: in the DESCRIPTION section. If there is\nconsensus about moving it somewhere else, I can send another patch.\n\n Documentation/git-revert.txt | 9 +++++++++\n 1 files changed, 9 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 98cfa3c..d46f090 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -15,6 +15,15 @@ Given one existing commit, revert the change the\npatch introduces, and record a\n new commit that records it. This requires your working tree to be clean (no\n modifications from the HEAD commit).\n\n+Note: Despite its name, 'git revert' may not undo changes in the way\n+that you expect. If you want to throw away all uncommitted changes in\n+your working directory, you should see linkgit:git-reset[1],\n+particulary the '--hard' option. If you want to extract specific\n+files as they were in another commit, you should see\n+linkgit:git-checkout[1], specifically the 'git checkout --\n+' syntax. Take care with these alternatives as both will\n+discard uncommitted changes in your working directory.\n+\n OPTIONS\n -------\n ::\n--\n1.6.0\n"},{"id":"87733","messageId":"7vk5ec7s05.fsf@gitster.siamese.dyndns.org","threadId":"15088","inReplyTo":"1219165591-19969-1-git-send-email-tarmigan+git@gmail.com","subject":"Re: [PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-08-19T18:56:58Z","receivedAt":"2008-08-19T18:56:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tarmigan Casebolt writes:\n\n> I put this in a Note: in the DESCRIPTION section. If there is\n> consensus about moving it somewhere else, I can send another patch.\n\nI think a note in the description would be fine.\n\n> +Note: Despite its name, 'git revert' may not undo changes in the way\n> +that you expect. If you want to throw away all uncommitted changes in\n> +your working directory, you should see linkgit:git-reset[1],\n> +particulary the '--hard' option. If you want to extract specific\n> +files as they were in another commit, you should see\n> +linkgit:git-checkout[1], specifically the 'git checkout --\n> +' syntax. Take care with these alternatives as both will\n> +discard uncommitted changes in your working directory.\n> +\n\nThe last sentence makes the paragraph incoherent, doesn't it?\n\nBy starting this paragraph with \"Despite its name\", you are stating your\nexpectation that the people who find \"git revert\" nonintuitive are the\nmajority. And you explain how to perform the operation that majority\nwould expect, which is to throw away uncommitted changes to go back to the\nclean slate. If that is what the target audience of this paragraph\nexpects to happen anyway, why do you need to caution against it in the\nlast sentence?\n\nIf the answer is \"because it is not cut-and-dried which expectation is the\nmajority, and we try to be careful not to lose local modifications of\nusers\", then the tone of the paragraph needs to become more neutral.\n\nI'd suggest either dropping the first sentence altogether and starting the\nparagraph with \"If you want to throw away...\", or replacing the first\nsentence with \"'git revert' is used to record a new commit to reverse the\neffect of an earlier commit (often a faulty one).\"\n"},{"id":"87744","messageId":"1219175431-20730-1-git-send-email-tarmigan+git@gmail.com","threadId":"15088","inReplyTo":"7vk5ec7s05.fsf@gitster.siamese.dyndns.org","subject":"[PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Tarmigan Casebolt","fromEmail":"tarmigan+git@gmail.com","sentAt":"2008-08-19T19:50:31Z","receivedAt":"2008-08-19T19:50:31Z","isPatch":true,"sender":{"key":"tarmigan+git@gmail.com","avatar":null},"body":"Based on its name, people may read the 'git revert' documentation when\nthey want to undo local changes, especially people who have used other\nSCM's. 'git revert' may not be what they had in mind, but git\nprovides several other ways to undo changes to files. We can help\nthem by pointing them towards the git commands that do what they might\nwant to do.\n\nCc: Daniel Barkalow \nCc: Lea Wiemann \nSigned-off-by: Tarmigan Casebolt \n---\n\nOn Tue, Aug 19, 2008 at 11:56 AM, Junio C Hamano wrote:\n> The last sentence makes the paragraph incoherent, doesn't it?\n\nYeah. My thinking was that the people who would appreciate this note\nwould be newbies, and it might be nice to warn them not to just try\n'git reset --hard' without thinking.\n\n> By starting this paragraph with \"Despite its name\", you are stating your\n> expectation that the people who find \"git revert\" nonintuitive are the\n> majority. \n>\n> And you explain how to perform the operation that majority\n> would expect, which is to throw away uncommitted changes to go back to the\n> clean slate. If that is what the target audience of this paragraph\n> expects to happen anyway, why do you need to caution against it in the\n> last sentence?\n\nI envision this note as useful for a majority of newbies who don't yet\nhave a sense of everything 'git reset' and 'git checkout' can do.\n\n> If the answer is \"because it is not cut-and-dried which expectation is the\n> majority, and we try to be careful not to lose local modifications of\n> users\", then the tone of the paragraph needs to become more neutral.\n>\n> I'd suggest either dropping the first sentence altogether and starting the\n> paragraph with \"If you want to throw away...\", or replacing the first\n> sentence with \"'git revert' is used to record a new commit to reverse the\n> effect of an earlier commit (often a faulty one).\"\n\nGood idea. I like the later option.\n\nThanks,\nTarmigan\n\n Documentation/git-revert.txt | 9 +++++++++\n 1 files changed, 9 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 98cfa3c..e578edf 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -15,7 +15,15 @@ Given one existing commit, revert the change the patch introduces, and record a\n new commit that records it. This requires your working tree to be clean (no\n modifications from the HEAD commit).\n \n+Note: 'git revert' is used to record a new commit to reverse the\n+effect of an earlier commit (often a faulty one). If you want to\n+throw away all uncommitted changes in your working directory, you\n+should see linkgit:git-reset[1], particularly the '--hard' option. If\n+you want to extract specific files as they were in another commit, you\n+should see linkgit:git-checkout[1], specifically the 'git checkout\n+ -- ' syntax. Take care with these alternatives as\n+both will discard uncommitted changes in your working directory.\n+\n OPTIONS\n -------\n ::\n-- \n1.6.0\n"},{"id":"87903","messageId":"7vzln7mglj.fsf@gitster.siamese.dyndns.org","threadId":"15088","inReplyTo":"1219175431-20730-1-git-send-email-tarmigan+git@gmail.com","subject":"Re: [PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-08-20T23:06:32Z","receivedAt":"2008-08-20T23:06:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tarmigan Casebolt writes:\n\n> Based on its name, people may read the 'git revert' documentation when\n> ...\n> Documentation/git-revert.txt | 9 +++++++++\n> 1 files changed, 9 insertions(+), 0 deletions(-)\n>\n> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\n> index 98cfa3c..e578edf 100644\n> --- a/Documentation/git-revert.txt\n> +++ b/Documentation/git-revert.txt\n> @@ -15,7 +15,15 @@ Given one existing commit, revert the change the patch introduces, and record a\n\nWhy do you say you have 7 preimage lines and 15 postimage lines, when the\ndiffstat claims you have 9 insertions?\n\nDid you hand edit the diff?\n"},{"id":"87904","messageId":"905315640808201636of09ccb3wb31b71cd090b451@mail.gmail.com","threadId":"15088","inReplyTo":"7vzln7mglj.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Tarmigan","fromEmail":"tarmigan+git@gmail.com","sentAt":"2008-08-20T23:36:40Z","receivedAt":"2008-08-20T23:36:40Z","isPatch":true,"sender":{"key":"tarmigan+git@gmail.com","avatar":null},"body":"On Wed, Aug 20, 2008 at 4:06 PM, Junio C Hamano wrote:\n> Tarmigan Casebolt writes:\n>\n>> Based on its name, people may read the 'git revert' documentation when\n>> ...\n>> Documentation/git-revert.txt | 9 +++++++++\n>> 1 files changed, 9 insertions(+), 0 deletions(-)\n>>\n>> diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\n>> index 98cfa3c..e578edf 100644\n>> --- a/Documentation/git-revert.txt\n>> +++ b/Documentation/git-revert.txt\n>> @@ -15,7 +15,15 @@ Given one existing commit, revert the change the patch introduces, and record a\n>\n> Why do you say you have 7 preimage lines and 15 postimage lines, when the\n> diffstat claims you have 9 insertions?\n>\n> Did you hand edit the diff?\n>\n\nOops, sorry about that. I did hand edit the diff because at the last\nsecond I saw a typo (particulary --> particularly), but I had already\nwritten the email so I didn't want to do `format-patch` again. I did\nnot rewrap, nor did I manually change the 6 to a 7. I did use emacs\nthough, which, when I tried to recreate it right now, seems to change\nthe 6 to a 7 when I touch any of the changed lines.\n\nSorry about that. I will turn off emacs diff mode and try to be more\ncareful next time. Please let me know if you want me to resend.\n\nThanks,\nTarmigan\n"},{"id":"87906","messageId":"7vvdxvmege.fsf@gitster.siamese.dyndns.org","threadId":"15088","inReplyTo":"905315640808201636of09ccb3wb31b71cd090b451@mail.gmail.com","subject":"Re: [PATCH] Add hints to revert documentation about other ways to undo changes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-08-20T23:52:49Z","receivedAt":"2008-08-20T23:52:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tarmigan writes:\n\n> On Wed, Aug 20, 2008 at 4:06 PM, Junio C Hamano wrote:\n> ..\n>> Did you hand edit the diff?\n>>\n> ... I did use emacs\n> though, which, when I tried to recreate it right now, seems to change\n> the 6 to a 7 when I touch any of the changed lines.\n\nOk, I was not complaining, just being curious.\n\nRecounting by Emacs's diff mode is sort of broken (it is not quite broken,\nbut it could do better). My primary interest in the question was to to\nsee if you are using some other broken diff editing environment.\n"}]}