{"thread":{"id":"29857","subject":"[PATCH] Documentation/git-rerere: document 'remaining' command","startedAt":"2012-03-06T12:21:52Z","lastAt":"2012-03-08T22:30:00Z","messageCount":8,"participants":["Vincent van Ravesteijn","Junio C Hamano","Phil Hord"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"186204","messageId":"1331036512-7626-1-git-send-email-vfr@lyx.org","threadId":"29857","inReplyTo":null,"subject":"[PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Vincent van Ravesteijn","fromEmail":"vfr@lyx.org","sentAt":"2012-03-06T12:21:52Z","receivedAt":"2012-03-06T12:21:52Z","isPatch":true,"sender":{"key":"vfr@lyx.org","avatar":"https://avatars.githubusercontent.com/u/687868?v=4"},"body":"From: Vincent van Ravesteijn \n\nThis adds the 'remaining' command to the documentation of\n'git rerere'. This command was added in ac49f5ca (Feb 16 2011;\nMartin von Zweigbergk ) but\nit was never documented.\n\nSigned-off-by: Vincent van Ravesteijn \n---\n Documentation/git-rerere.txt | 10 +++++++++-\n 1 files changed, 9 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex a6253ba..b75d34b 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' |'diff'|'status'|'gc']\n+'git rerere' ['clear'|'forget' |'diff'|'remaining'|'status'|'gc']\n \n DESCRIPTION\n -----------\n@@ -53,6 +53,14 @@ useful for tracking what has changed while the user is resolving\n conflicts. Additional arguments are passed directly to the system\n 'diff' command installed in PATH.\n \n+'remaining'::\n+\n+Like 'diff', but this only prints the unresolved filenames. This\n+includes the files for which rerere tracks the resolution (as shown\n+by 'git rerere status'), but also the files for which the conflicts\n+cannot be tracked by rerere, e.g. files with conflicts that do not \n+have both our side and their side like \"we modified, they deleted\".\n+\n 'status'::\n \n Like 'diff', but this only prints the filenames that will be tracked\n-- \n1.7.5.4\n"},{"id":"186239","messageId":"7vwr6xsfbn.fsf@alter.siamese.dyndns.org","threadId":"29857","inReplyTo":"1331036512-7626-1-git-send-email-vfr@lyx.org","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-06T19:24:28Z","receivedAt":"2012-03-06T19:24:28Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Vincent van Ravesteijn writes:\n\n> From: Vincent van Ravesteijn \n>\n> This adds the 'remaining' command to the documentation of\n> 'git rerere'. This command was added in ac49f5ca (Feb 16 2011;\n> Martin von Zweigbergk ) but\n> it was never documented.\n>\n> Signed-off-by: Vincent van Ravesteijn \n> ---\n> Documentation/git-rerere.txt | 10 +++++++++-\n> 1 files changed, 9 insertions(+), 1 deletions(-)\n>\n> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\n> index a6253ba..b75d34b 100644\n> --- a/Documentation/git-rerere.txt\n> +++ b/Documentation/git-rerere.txt\n> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n> SYNOPSIS\n> --------\n> [verse]\n> -'git rerere' ['clear'|'forget' |'diff'|'status'|'gc']\n> +'git rerere' ['clear'|'forget' |'diff'|'remaining'|'status'|'gc']\n> \n> DESCRIPTION\n> -----------\n> @@ -53,6 +53,14 @@ useful for tracking what has changed while the user is resolving\n> conflicts. Additional arguments are passed directly to the system\n> 'diff' command installed in PATH.\n> \n> +'remaining'::\n> +\n> +Like 'diff', but this only prints the unresolved filenames. This\n\nWhat aspect of 'rerere remaining' is like 'rerere diff'?\n\nIn general, people should think twice after writing \"Like X, but Y\"\nand try to come up with a more clear description that does not have\nto force the user to read about X and then selectively forget what\nhe just read and replace it with Y. This is especially true when the\nY part is significantly different from what X does.\n\nAnother phrase to watch out for when writing documentation is \"X. In\nother words, Y.\" People do this after writing X and finding it hard\nto understand and necessary to explain in easier terms. Reading it\nagain without \"X. In other words, \" often yields a better description.\n\n\t'remaining'::\n\n Print paths with conflicts that are not resolved.\n\nShould be sufficient, I think.\n\nIn fact, wouldn't this be more or less equivalent to \"ls-files -u\"\nwithout anything other than name part?\n"},{"id":"186345","messageId":"CABURp0rOFgwLu0pX0W5txOH=CH6Yb4NchYLaj91m1nMve_zjDg@mail.gmail.com","threadId":"29857","inReplyTo":"7vwr6xsfbn.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Phil Hord","fromEmail":"phil.hord@gmail.com","sentAt":"2012-03-07T22:10:48Z","receivedAt":"2012-03-07T22:10:48Z","isPatch":true,"sender":{"key":"phil.hord@gmail.com","avatar":"https://avatars.githubusercontent.com/u/123908?v=4"},"body":"On Tue, Mar 6, 2012 at 2:24 PM, Junio C Hamano wrote:\n> Vincent van Ravesteijn writes:\n>\n>> From: Vincent van Ravesteijn \n>>\n>> This adds the 'remaining' command to the documentation of\n>> 'git rerere'. This command was added in ac49f5ca (Feb 16 2011;\n>> Martin von Zweigbergk ) but\n>> it was never documented.\n>>\n>> Signed-off-by: Vincent van Ravesteijn \n>> ---\n>>  Documentation/git-rerere.txt |   10 +++++++++-\n>>  1 files changed, 9 insertions(+), 1 deletions(-)\n>>\n>> diff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\n>> index a6253ba..b75d34b 100644\n>> --- a/Documentation/git-rerere.txt\n>> +++ b/Documentation/git-rerere.txt\n>> @@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n>>  SYNOPSIS\n>>  --------\n>>  [verse]\n>> -'git rerere' ['clear'|'forget' |'diff'|'status'|'gc']\n>> +'git rerere' ['clear'|'forget' |'diff'|'remaining'|'status'|'gc']\n>>\n>>  DESCRIPTION\n>>  -----------\n>> @@ -53,6 +53,14 @@ useful for tracking what has changed while the user is resolving\n>>  conflicts.  Additional arguments are passed directly to the system\n>>  'diff' command installed in PATH.\n>>\n>> +'remaining'::\n>> +\n>> +Like 'diff', but this only prints the unresolved filenames. This\n>\n[...]\n>\n>        'remaining'::\n>\n>        Print paths with conflicts that are not resolved.\n>\n> Should be sufficient, I think.\n>\n> In fact, wouldn't this be more or less equivalent to \"ls-files -u\"\n> without anything other than name part?\n\nNo. When using --no-rerere-autoupdate, git does not add autoresolved\nfiles to the index; it fixes them only in your working directory.\n'ls-files -u' still lists them as unresolved. 'rerere remaining' does\nnot list these autoresolved files. 'mergetool' uses this command to\navoid asking the user to resolve files which git rerere already\nresolved for her.\n\nac49f5ca8 has a pretty complete description, though it may be a bit\ntoo wordy for the the up-front synopsis.\n2f59c9470 has a more complete justification.\n\nPhil\n"},{"id":"186350","messageId":"7vvcmgkq20.fsf@alter.siamese.dyndns.org","threadId":"29857","inReplyTo":"CABURp0rOFgwLu0pX0W5txOH=CH6Yb4NchYLaj91m1nMve_zjDg@mail.gmail.com","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-07T22:24:23Z","receivedAt":"2012-03-07T22:24:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phil Hord writes:\n\n> On Tue, Mar 6, 2012 at 2:24 PM, Junio C Hamano wrote:\n> ...\n>> 'remaining'::\n>>\n>> Print paths with conflicts that are not resolved.\n>>\n>> Should be sufficient, I think.\n>\n> .... 'mergetool' uses this command to\n> avoid asking the user to resolve files which git rerere already\n> resolved for her.\n\nOk, so \"Print paths with conflicts that are not resolved.\" indeed is\nsufficient.\n"},{"id":"186370","messageId":"CABURp0run5zYLBkUsNQEJq3h_1y7bQ44XZb9BPja+RjX8OLyfg@mail.gmail.com","threadId":"29857","inReplyTo":"7vvcmgkq20.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Phil Hord","fromEmail":"phil.hord@gmail.com","sentAt":"2012-03-08T03:08:16Z","receivedAt":"2012-03-08T03:08:16Z","isPatch":true,"sender":{"key":"phil.hord@gmail.com","avatar":"https://avatars.githubusercontent.com/u/123908?v=4"},"body":"On Wed, Mar 7, 2012 at 5:24 PM, Junio C Hamano wrote:\n> Phil Hord writes:\n>\n>> On Tue, Mar 6, 2012 at 2:24 PM, Junio C Hamano wrote:\n>> ...\n>>>        'remaining'::\n>>>\n>>>        Print paths with conflicts that are not resolved.\n>>>\n>>> Should be sufficient, I think.\n>>\n>> ....  'mergetool' uses this command to\n>> avoid asking the user to resolve files which git rerere already\n>> resolved for her.\n>\n> Ok, so \"Print paths with conflicts that are not resolved.\" indeed is\n> sufficient.\n\nIf you goal is to say as little as possible, then yes. But I had to\nread the related commit messages several times before it dawned on me\nwhat the distinction was. The main problem was that I didn't\nunderstand that I was missing 'rerere.autoupdate=true' in my config,\nor why it mattered. I only know that rerere was letting me down\nsometimes, and 'rerere remaining' seemed to be missing some\nclearly-still-unresolved files.\n\nThanks to this proposal, I understand it better now. But not from\nreading this email thread.\n\nPhil\n"},{"id":"186373","messageId":"7vr4x3is39.fsf@alter.siamese.dyndns.org","threadId":"29857","inReplyTo":"CABURp0run5zYLBkUsNQEJq3h_1y7bQ44XZb9BPja+RjX8OLyfg@mail.gmail.com","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-08T05:23:22Z","receivedAt":"2012-03-08T05:23:22Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phil Hord writes:\n\n>>> .... 'mergetool' uses this command to\n>>> avoid asking the user to resolve files which git rerere already\n>>> resolved for her.\n>>\n>> Ok, so \"Print paths with conflicts that are not resolved.\" indeed is\n>> sufficient.\n>\n> If you goal is to say as little as possible, then yes. But I had to\n> read the related commit messages several times before it dawned on me\n> what the distinction was.\n\nThe goal is \"Concise, coherent and clear\"; \"as little as possible\"\nnever is. We need to elaborate as needed but make sure we do not\ntire readers with irrelevant explanation.\n\nThe first problem I had with the patch (go back and re-read the\npatch and its initial review) was \"Like 'diff', but...\". It is not\n\"Like diff\" at all (if anything, it is more like \"status\", but\n\"status\" in turn is not \"Like diff\" either). We can first drop that\npart and spend more words to describe what it really is.\n\n> The main problem was that I didn't\n> understand that I was missing 'rerere.autoupdate=true' in my config,\n> or why it mattered. I only know that rerere was letting me down\n> sometimes, and 'rerere remaining' seemed to be missing some\n> clearly-still-unresolved files.\n\nPersonally, I think you are being *good* by not using autoupdate.\nOnce you let rerere auto-update, it will become hard to notice a\nmismerge when previous resolution is applied when it shouldn't, and\neven harder to correct it (\"checkout -m\" will not work).\n\n> Thanks to this proposal, I understand it better now. But not from\n> reading this email thread.\n\nCare to give a crack at it, then?\n"},{"id":"186495","messageId":"CABURp0pd4wAw0ax5jjaoOR-bAWUGUQa-k1xby9_Bb_wQwsLk7w@mail.gmail.com","threadId":"29857","inReplyTo":"7vr4x3is39.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Phil Hord","fromEmail":"phil.hord@gmail.com","sentAt":"2012-03-08T21:08:50Z","receivedAt":"2012-03-08T21:08:50Z","isPatch":true,"sender":{"key":"phil.hord@gmail.com","avatar":"https://avatars.githubusercontent.com/u/123908?v=4"},"body":"On Thu, Mar 8, 2012 at 12:23 AM, Junio C Hamano wrote:\n> Phil Hord writes:\n>\n>>>> .... 'mergetool' uses this command to\n>>>> avoid asking the user to resolve files which git rerere already\n>>>> resolved for her.\n>>>\n>>> Ok, so \"Print paths with conflicts that are not resolved.\" indeed is\n>>> sufficient.\n>>\n>> If you goal is to say as little as possible, then yes.  But I had to\n>> read the related commit messages several times before it dawned on me\n>> what the distinction was.\n>\n> The goal is \"Concise, coherent and clear\"; \"as little as possible\"\n> never is.  We need to elaborate as needed but make sure we do not\n> tire readers with irrelevant explanation.\n>\n> The first problem I had with the patch (go back and re-read the\n> patch and its initial review) was \"Like 'diff', but...\".  It is not\n> \"Like diff\" at all (if anything, it is more like \"status\", but\n> \"status\" in turn is not \"Like diff\" either). We can first drop that\n> part and spend more words to describe what it really is.\n\nNo disagreement here.\n\n>> The main problem was that I didn't\n>> understand that I was missing 'rerere.autoupdate=true' in my config,\n>> or why it mattered. I only know that rerere was letting me down\n>> sometimes, and 'rerere remaining' seemed to be missing some\n>> clearly-still-unresolved files.\n>\n> Personally, I think you are being *good* by not using autoupdate.\n> Once you let rerere auto-update, it will become hard to notice a\n> mismerge when previous resolution is applied when it shouldn't, and\n> even harder to correct it (\"checkout -m\" will not work).\n\nSlightly off-topic, but here's why autoupdate=false is a problem, and\nwhy I thought rerere-remaining was broken for the last year. When I\nrebase a branch, git magically plows through dozens of commits and\nstops to tell me when there's a merge conflict that needs my\nattention. Not having a GUI means I have to do something (type\ncommands or parse output) to see what's happened. But the solution to\n\"resolve these conflicts\" is always the same: git-mergetool && git\nrebase --continue.\n\nExcept with rerere enabled.\n\n $ git rebase origin/master\n Noise, noise, noise\n Resolved 'foo' using previous resolution.\n Failed to merge in the changes.\n\nI reach for my utility belt, but my usual tricks all fail at this point:\n\n $ git mergetool\n No files need merging\n\n $ git rebase --continue\n foo: needs merge\n\n $ git diff foo\n diff --cc foo\n index 5716ca5,7601807..0000000\n --- i/foo\n +++ w/foo\n\nThe last one looks to me, the uninitiated, like a file with no\nchanges. I know better now, but I didn't before. The only thing that\nworks is this, but I didn't know why:\n\n $ git add foo\n\nNow I know why, and it just pisses me off. I thought rerere was\nsupposed to save me from this drudgery, especially when I am rebasing\nthe same branch multiple times (part of a migration effort).\n\nI think I know the solution now. 'mergetool' should never have\nignored these files. Instead, it should tell me about them:\n\n $ git mergetool\n Merging:\n foo\n\n Normal merge conflict for 'foo' was resolved using previous resolution.\n hint: to re-examine the resolution, use \"git diff -c foo\"\n hint: to accept this resolution, add it to the index with \"git add foo\"\n\n No more files need merging.\n\nI didn't know how to spell \"diff -c\" before, but I also didn't know it\nwas what I needed\n\n>> Thanks to this proposal, I understand it better now.  But not from\n>> reading this email thread.\n>\n> Care to give a crack at it, then?\n\nYeah, right. Remember, it took me three tries reading the actual\ncommit messages to understand what was even going on. I'm probably\ntoo thick for this.\n\nHow's this:\n\n-- >8 --\nSubject: [PATCH] rerere: Document 'rerere remaining'\n\nThis adds the 'remaining' command to the documentation of\n'git rerere'. This command was added in ac49f5ca (Feb 16 2011;\nMartin von Zweigbergk ) but\nit was never documented.\n\nTouch up the other rerere commands to reduce noise.\n\nSigned-off-by: Phil Hord \nSigned-off-by: Vincent van Ravesteijn \n---\nDo you think the touch-ups are overkill?\nAlso, I think 'rerere diff' could use a rewrite.\n\n Documentation/git-rerere.txt | 19 ++++++++++++-------\n 1 file changed, 12 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-rerere.txt b/Documentation/git-rerere.txt\nindex a6253ba..b43b7c8 100644\n--- a/Documentation/git-rerere.txt\n+++ b/Documentation/git-rerere.txt\n@@ -8,7 +8,7 @@ git-rerere - Reuse recorded resolution of conflicted merges\n SYNOPSIS\n --------\n [verse]\n-'git rerere' ['clear'|'forget' |'diff'|'status'|'gc']\n+'git rerere' ['clear'|'forget' |'diff'|'remaining'|'status'|'gc']\n\n DESCRIPTION\n -----------\n@@ -37,30 +37,35 @@ its working state.\n\n 'clear'::\n\n-This resets the metadata used by rerere if a merge resolution is to be\n+Reset the metadata used by rerere if a merge resolution is to be\n aborted. Calling 'git am [--skip|--abort]' or 'git rebase [--skip|--abort]'\n will automatically invoke this command.\n\n 'forget' ::\n\n-This resets the conflict resolutions which rerere has recorded for the current\n+Reset the conflict resolutions which rerere has recorded for the current\n conflict in .\n\n 'diff'::\n\n-This displays diffs for the current state of the resolution. It is\n+Display diffs for the current state of the resolution. It is\n useful for tracking what has changed while the user is resolving\n conflicts. Additional arguments are passed directly to the system\n 'diff' command installed in PATH.\n\n 'status'::\n\n-Like 'diff', but this only prints the filenames that will be tracked\n-for resolutions.\n+Print paths with conflicts whose merge resolution rerere will record.\n+\n+'remaining'::\n+\n+Print paths with conflicts that have not been autoresolved by rerere.\n+This includes paths whose resolutions cannot be tracked by rerere,\n+such as conflicting submodules.\n\n 'gc'::\n\n-This prunes records of conflicted merges that\n+Prune records of conflicted merges that\n occurred a long time ago. By default, unresolved conflicts older\n than 15 days and resolved conflicts older than 60\n days are pruned. These defaults are controlled via the\n-- \n1.7.9.3\n"},{"id":"186507","messageId":"7veht2buaf.fsf@alter.siamese.dyndns.org","threadId":"29857","inReplyTo":"CABURp0pd4wAw0ax5jjaoOR-bAWUGUQa-k1xby9_Bb_wQwsLk7w@mail.gmail.com","subject":"Re: [PATCH] Documentation/git-rerere: document 'remaining' command","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-03-08T22:30:00Z","receivedAt":"2012-03-08T22:30:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phil Hord writes:\n\n> On Thu, Mar 8, 2012 at 12:23 AM, Junio C Hamano wrote:\n>> Phil Hord writes:\n> ...\n> $ git rebase origin/master\n> Noise, noise, noise\n> Resolved 'foo' using previous resolution.\n> Failed to merge in the changes.\n>\n> I reach for my utility belt, but my usual tricks all fail at this point:\n>\n> $ git mergetool\n> No files need merging\n>\n> $ git rebase --continue\n> foo: needs merge\n\nJust to make sure we are on the same page (I do not personally use\n\"mergetool\"), the above looks like a bug in mergetool.\n\nAre you reporting a still-unfixed breakage, or is it an anecdote on\nhow you were frustrated in the past due to a bug that has since been\nfixed?\n\n> How's this:\n\nLooks good.\n\n> 'status'::\n>\n> -Like 'diff', but this only prints the filenames that will be tracked\n> -for resolutions.\n> +Print paths with conflicts whose merge resolution rerere will record.\n> +\n> +'remaining'::\n> +\n> +Print paths with conflicts that have not been autoresolved by rerere.\n> +This includes paths whose resolutions cannot be tracked by rerere,\n> +such as conflicting submodules.\n\nWe might want to add \"and a path that was deleted by one branch and\nmodified by the other branch\" at the end here.\n\nUnless an earlier part of the documentation that discusses what kind\nof resolutions get recorded and reapplied makes it clear enough that\nthe reader can easily guess a delete/modify conflict is not handled,\nthat is. I _think_ the description at the top makes it clear the\ntwo branches being merged both need to have a file at the path, so\nin that sense, singling out delete/modify and mentioning it here\nmight be redundant, but I am not the target audience (I wrote and\nnamed it rerere after all ;-), so I shouldn't be my own judge.\n\nThanks.\n"}]}