{"thread":{"id":"31738","subject":"git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","startedAt":"2012-10-05T14:20:45Z","lastAt":"2012-10-11T17:57:26Z","messageCount":16,"participants":["Horst H. von Brand","Frans Klaver","Junio C Hamano","Jeff King","Conrad Irwin"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"200627","messageId":"201210051420.q95EKjj3008300@netbook1.inf.utfsm.cl","threadId":"31738","inReplyTo":null,"subject":"git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Horst H. von Brand","fromEmail":"vonbrand@inf.utfsm.cl","sentAt":"2012-10-05T14:20:45Z","receivedAt":"2012-10-05T14:20:45Z","isPatch":false,"sender":{"key":"vonbrand@inf.utfsm.cl","avatar":"https://avatars.githubusercontent.com/u/211384?v=4"},"body":"What I did:\n\n- New file images/coins.asy ~~-> 'git add images/coins.asy'\n- Started adding new stuff to fg.tex\n- Noticed a old bug in fg.tex, fixed that one\n- Did 'git -pm \"Some message\"' and selected just the bugfix\n\nBut git created a commit _including_ the new file. Tried to go back:\n\n- 'git reset HEAD^'\n\nNow the new file isn't staged anymore\n\n\nWhat I expected to happen:\n\n- Only the explicitly selected chunks commited\n- No \"losing staged changes\"\n-- \nDr. Horst H. von Brand User #22616 counter.li.org\nDepartamento de Informatica Fono: +56 32 2654431\nUniversidad Tecnica Federico Santa Maria +56 32 2654239\nCasilla 110-V, Valparaiso, Chile 2340000 Fax: +56 32 2797513\n"},{"id":"200635","messageId":"op.wlp1lws70aolir@keputer","threadId":"31738","inReplyTo":"201210051420.q95EKjj3008300@netbook1.inf.utfsm.cl","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Frans Klaver","fromEmail":"fransklaver@gmail.com","sentAt":"2012-10-05T19:55:07Z","receivedAt":"2012-10-05T19:55:07Z","isPatch":false,"sender":{"key":"fransklaver@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1876483?v=4"},"body":"On Fri, 05 Oct 2012 16:20:45 +0200, Horst H. von Brand \n wrote:\n\n> What I did:\n>\n> - New file images/coins.asy ~~-> 'git add images/coins.asy'\n> - Started adding new stuff to fg.tex\n> - Noticed a old bug in fg.tex, fixed that one\n> - Did 'git -pm \"Some message\"' and selected just the bugfix\n>\n> But git created a commit _including_ the new file. Tried to go back:\n\nExactly what's supposed to happen. \"git add\" tells git you want to add the \nfile to the index. The index is what you're going to commit later on. So \nwhat you did there was\n\n- Tell git to add images/coins.asy to the next commit\n- hack hack hack\n- fix old_bug\n- Add old_bug chunks of code to next commit && create commit\n\n>\n> - 'git reset HEAD^'\n>\n> Now the new file isn't staged anymore\n>\n>\n> What I expected to happen:\n>\n> - Only the explicitly selected chunks commited\n> - No \"losing staged changes\"\n\nAs explained above, you didn't lose staged changes, you staged more \nchanges and committed. Then you use git reset to go back to the state of \nHEAD^, where the file wasn't tracked and therefore not staged either.\n\nSo you're back at square one[1], commit the bug fix, then add the bugfixes \nin a commit and stage the new file for inclusion in your next commit.\n\nHope this helps,\nFrans\n\n[1] Arguably two, since you still have changes lying around.\n"},{"id":"200643","messageId":"7vsj9ssgcp.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"op.wlp1lws70aolir@keputer","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-05T22:29:10Z","receivedAt":"2012-10-05T22:29:10Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Frans Klaver\" writes:\n\n> On Fri, 05 Oct 2012 16:20:45 +0200, Horst H. von Brand\n> wrote:\n>\n>> What I did:\n>>\n>> - New file images/coins.asy ~~-> 'git add images/coins.asy'\n>> - Started adding new stuff to fg.tex\n>> - Noticed a old bug in fg.tex, fixed that one\n>> - Did 'git -pm \"Some message\"' and selected just the bugfix\n>>\n>> But git created a commit _including_ the new file. Tried to go back:\n>\n> Exactly what's supposed to happen. \"git add\" tells git you want to add\n> the file to the index. The index is what you're going to commit later\n> on.\n\nAssuming that the last step of what Horst did was \"git commit -pm\",\nI think Git is wrong in this case. When you tell \"git commit\" what\nto commit, unless you give \"-i\" (aka \"also\") option, the command\nmakes a commit to record changes only from what you tell \"git\ncommit\" to commit, regardless of what you earlier did to the index.\n\nAnd choosing what to add via the interactive interface is in the\nsame spirit as telling what to commit to \"git commit\", so it should\nbehave the same.\n\nThis is one of the times I wish I said \"No, you cannot have a pony\".\nThe change was done without thinking things through, and reviewers\nincluding me did not realize this particular downside. My accepting\nthis misfeature (or a poorly implemented feature that has a\npotential to be useful) was essentially me saying:\n\n When making a commit that does not match my working tree state,\n I always check with \"diff --cached\" to make sure what I think I\n am committing matches what I am committing, so I won't use such\n a lazy option myself. I am not excited to think things through\n to see what possible pitfalls the feature may have for you; I'll\n let you guys hang yourself with that long rope.\n\nAnd we are seeing a backfire from that \"not bothering to think\nthings thorough\".\n\nI think the right thing to do is to fix \"git commit -p\" so that it\nstarts from the HEAD (on a temporary index), just like how partial\ncommits are made with \"git commit file1 file2\". Or just forbid it\nwhen the index does not match HEAD.\n\nCf. \n\n http://thread.gmane.org/gmane.comp.version-control.git/173033/focus=173246\n"},{"id":"200644","messageId":"20121005225758.GA1202@sigill.intra.peff.net","threadId":"31738","inReplyTo":"7vsj9ssgcp.fsf@alter.siamese.dyndns.org","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-05T22:57:58Z","receivedAt":"2012-10-05T22:57:58Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 05, 2012 at 03:29:10PM -0700, Junio C Hamano wrote:\n\n> Assuming that the last step of what Horst did was \"git commit -pm\",\n> I think Git is wrong in this case. When you tell \"git commit\" what\n> to commit, unless you give \"-i\" (aka \"also\") option, the command\n> makes a commit to record changes only from what you tell \"git\n> commit\" to commit, regardless of what you earlier did to the index.\n\nYeah. Defaulting to \"-o\" would match the rest of git-commit's behavior\nmuch better.\n\n> This is one of the times I wish I said \"No, you cannot have a pony\".\n> The change was done without thinking things through, and reviewers\n> including me did not realize this particular downside.\n> [...]\n> Cf. \n> \n> http://thread.gmane.org/gmane.comp.version-control.git/173033/focus=173246\n\nActually, I am not sure that thread or feature is to blame. Certainly it\nwould have been an opportune time to notice the problem. But this issue\ngoes back much further for \"git commit --interactive\", which has always\nassumed \"-i\" rather than \"-o\". This even predates the switch from shell\nto C; you can see the same behavior from 6cbf07e (git-commit: add a\n--interactive option, 2007-03-05).\n\nI guess you could argue that \"--interactive\" and \"--patch\" should have\ndifferent defaults, but I'm not sure I agree. They should both match\nwhat \"git commit foo\" does by default.\n\n> I think the right thing to do is to fix \"git commit -p\" so that it\n> starts from the HEAD (on a temporary index), just like how partial\n> commits are made with \"git commit file1 file2\". Or just forbid it\n> when the index does not match HEAD.\n\nAgreed. I am inclined to call this a bugfix, though it does worry me\nslightly that we would be changing a behavior that has existed for so\nmany years.\n\nWe should probably also support explicit \"-i -p\" and \"-o -p\" options, as\nwell (the former would give people who really want the existing behavior\na way to get it). And the same for \"--interactive\". I can't say I'm\nexcited about making all that work, though. Like you, I think it is more\nsane to use existing tools to inspect and tweak the index to your\nliking, and then commit.\n\n-Peff\n"},{"id":"200651","messageId":"7v8vbkru8o.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"20121005225758.GA1202@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-06T06:26:47Z","receivedAt":"2012-10-06T06:26:47Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Actually, I am not sure that thread or feature is to blame. Certainly it\n> would have been an opportune time to notice the problem. But this issue\n> goes back much further for \"git commit --interactive\", which has always\n> assumed \"-i\" rather than \"-o\". This even predates the switch from shell\n> to C; you can see the same behavior from 6cbf07e (git-commit: add a\n> --interactive option, 2007-03-05).\n\nYes. That was after we started defaulting to \"only\" (not \"also\")\nsemantics when the command is run with paths, and it should also\nhave raised a red flag to reviewers.\n\nIn the case of \"add/commit --interactive\", it is much more clear\nwhat state the index is in when the command gave interactive control\nto the user. The short-cut \"add/commit -p\" interface, however, does\nnot give you an access to its s)tatus subcommand, making the user\nexperience somewhat different.\n\nThat makes the problem much more severe for \"-p\" compared to\n\"--interactive\", but the fundamental UI consistency it introduces is\nthe same as the issue under discussion in this thread.\n\n>> I think the right thing to do is to fix \"git commit -p\" so that it\n>> starts from the HEAD (on a temporary index), just like how partial\n>> commits are made with \"git commit file1 file2\". Or just forbid it\n>> when the index does not match HEAD.\n>\n> Agreed. I am inclined to call this a bugfix, though it does worry me\n> slightly that we would be changing a behavior that has existed for so\n> many years.\n\nI agree it will be a bugfix, but I am afraid that the fix may have\nto be much more involved than \"start from a temporary index that\nmatches HEAD when we are doing the '--only' semantics\".\n\nSuppose you have two paths E and F, both of which have differences\nbetween HEAD and the index, and the index and the working tree file\n(i.e. you earlier edited E and F, did \"git add E F\" and further\nedited them).\n\nYou say \"git commit -p F\".\n\nWhat should happen? It is clear that the resulting commit should\nrecord no change since its parent commit at path E (that is what\n\"only\" semantics mean).\n\nWhat state should the \"add -p\" interaction start from for path F?\nShould you be picking from a patch between the state you previously\n\"git add\"ed to the index and the working tree, or should the entire\ndifference between HEAD and the working tree eligible to be picked\nor deferred during the \"add -p\" session? Starting from a temporary\nindex that matches HEAD essentially means that you lose the earlier\n\"git add F\" [*1*].\n\nAnother case to consider is to start from the same condition, and\ninstead to say \"git commit -p\" without any pathspec. What should\nhappen?\n\nJust doing \"use a temporary index that is initialized to HEAD\" may\nbe an expedient thing to do, but I suspect that I will be saying the\nsame \"I should have said 'You cannot have a pony' back then\" again\nin a not so distant future if we did so without thinking these\nthings through.\n\nAs I do not see any practical value in \"commit -p\", I do not think\nit is worth my time thinking these things through thoroughly myself.\n\nUnless somebody who cares about \"commit -p\" does so to come up with\nreasonable semantics, and updates the code to match that desired\nbehaviour, the responsible thing to do is to error out \"-p\" when\nyour index is different from HEAD, I think.\n\n\n[Footnote]\n\n*1* A not-so-deep thinking of the above might lead to \"start from\nthe index that match HEAD, except for paths specified on the\npathspec given to the -p option\". But I do not think it is\nsatisfactory, either. With \"add -i\" (or \"commit --interactive\"),\nyou have an option to selectively discard parts of your previous,\noverzealous \"git add F\" with its r)evert action, but because \"commit\n-p\" does not give an option to switch to \"reset -p\", you can only\nadd hunks, People who did \"git add E F\" earlier and then wants to\namend that earlier add with \"git commit -p F\", but it does not allow\nthem to fully amend their earlier action. That is the one of the\nreasons why I think \"commit -p\" is a mistaken \"we can save one\ncommand invocation\" false economy that adds confusion without adding\nmuch value to the UI.\n"},{"id":"200663","messageId":"20121006131200.GB11712@sigill.intra.peff.net","threadId":"31738","inReplyTo":"7v8vbkru8o.fsf@alter.siamese.dyndns.org","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-06T13:12:00Z","receivedAt":"2012-10-06T13:12:00Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Oct 05, 2012 at 11:26:47PM -0700, Junio C Hamano wrote:\n\n> In the case of \"add/commit --interactive\", it is much more clear\n> what state the index is in when the command gave interactive control\n> to the user. The short-cut \"add/commit -p\" interface, however, does\n> not give you an access to its s)tatus subcommand, making the user\n> experience somewhat different.\n> \n> That makes the problem much more severe for \"-p\" compared to\n> \"--interactive\", but the fundamental UI consistency it introduces is\n> the same as the issue under discussion in this thread.\n\nAgreed.\n\n> Suppose you have two paths E and F, both of which have differences\n> between HEAD and the index, and the index and the working tree file\n> (i.e. you earlier edited E and F, did \"git add E F\" and further\n> edited them).\n> \n> You say \"git commit -p F\".\n> \n> What should happen? It is clear that the resulting commit should\n> record no change since its parent commit at path E (that is what\n> \"only\" semantics mean).\n> \n> What state should the \"add -p\" interaction start from for path F?\n> Should you be picking from a patch between the state you previously\n> \"git add\"ed to the index and the working tree, or should the entire\n> difference between HEAD and the working tree eligible to be picked\n> or deferred during the \"add -p\" session? Starting from a temporary\n> index that matches HEAD essentially means that you lose the earlier\n> \"git add F\" [*1*].\n> \n> Another case to consider is to start from the same condition, and\n> instead to say \"git commit -p\" without any pathspec. What should\n> happen?\n\nHmm. Good questions. In the former case, I would have said you should\ndefinitely omit E and then start from the staged point of F, as that is\nalmost certainly what the user meant. But that is utterly inconsistent\nwith what we are discussing for the no-pathspec case.\n\nI have a gut feeling that what I would expect for \"-p\" is roughly:\n\n 1. Feed add--interactive the current index state.\n\n 2. Feed add--interactive the set of pathspecs on the command line to\n limit its work.\n\n 3. For any path that is updated by the interactive session, keep the\n result.\n\n 4. For other paths, revert to HEAD.\n\nI think that would \"do what I mean\" most of the time. But it is a\nhorrible set of rules to try to explain to someone (and it is off the\ntop of my head; I wouldn't be surprised if you can come up with a\nsituation where those rules do not behave well).\n\n> Just doing \"use a temporary index that is initialized to HEAD\" may\n> be an expedient thing to do, but I suspect that I will be saying the\n> same \"I should have said 'You cannot have a pony' back then\" again\n> in a not so distant future if we did so without thinking these\n> things through.\n> \n> As I do not see any practical value in \"commit -p\", I do not think\n> it is worth my time thinking these things through thoroughly myself.\n> \n> Unless somebody who cares about \"commit -p\" does so to come up with\n> reasonable semantics, and updates the code to match that desired\n> behaviour, the responsible thing to do is to error out \"-p\" when\n> your index is different from HEAD, I think.\n\nYeah. I did not agree with your conclusion here when we started the\nconversation, but I am starting to now. I am not opposed at all to\nsomebody working out the semantics, but I do not really care to work on\nit myself. In the meantime, I would rather not do any halfway fixes\nthat will just make things worse.\n\nAnother option is to leave it with \"-i\" semantics in the meantime, which\nare at least easy to explain: it is simply a shorthand for running \"git\nadd -p && git commit\". That may be inconsistent with other aspects of\ncommit, but people have (apparently) been happy with it, and there has\nnot been a rash of complaints.\n\nAs a non-user of \"commit -p\" myself, I don't have a strong opinion\neither way.\n\n-Peff\n"},{"id":"200677","messageId":"7vvcenqx39.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"20121006131200.GB11712@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-06T18:22:50Z","receivedAt":"2012-10-06T18:22:50Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Another option is to leave it with \"-i\" semantics in the meantime, which\n> are at least easy to explain: it is simply a shorthand for running \"git\n> add -p && git commit\". That may be inconsistent with other aspects of\n> commit, but people have (apparently) been happy with it, and there has\n> not been a rash of complaints.\n\nYeah, that would be the safest and possibly the sanest way forward.\nDid the documentation update patch by Conrad on the other subthread\nlook sane to you? I haven't read it very carefully yet.\n"},{"id":"200680","messageId":"20121006183026.GA3644@sigill.intra.peff.net","threadId":"31738","inReplyTo":"7vvcenqx39.fsf@alter.siamese.dyndns.org","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-06T18:30:26Z","receivedAt":"2012-10-06T18:30:26Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Oct 06, 2012 at 11:22:50AM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > Another option is to leave it with \"-i\" semantics in the meantime, which\n> > are at least easy to explain: it is simply a shorthand for running \"git\n> > add -p && git commit\". That may be inconsistent with other aspects of\n> > commit, but people have (apparently) been happy with it, and there has\n> > not been a rash of complaints.\n> \n> Yeah, that would be the safest and possibly the sanest way forward.\n> Did the documentation update patch by Conrad on the other subthread\n> look sane to you? I haven't read it very carefully yet.\n\nI didn't notice any documentation patch, and I can't find one looking\nthrough the archive. Do you have a link?\n\n-Peff\n"},{"id":"200681","messageId":"CAOTq_pu=xWF7q3QobxSerkkbV56n5o+CPQSyHg8onwv73v25+A@mail.gmail.com","threadId":"31738","inReplyTo":"20121006183026.GA3644@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Conrad Irwin","fromEmail":"conrad.irwin@gmail.com","sentAt":"2012-10-06T18:32:51Z","receivedAt":"2012-10-06T18:32:51Z","isPatch":false,"sender":{"key":"conrad.irwin@gmail.com","avatar":"https://avatars.githubusercontent.com/u/94272?v=4"},"body":"I think I messed up sending somehow:\n\nOn Fri, Oct 5, 2012 at 11:26 PM, Junio C Hamano wrote:\n> Suppose you have two paths E and F, both of which have differences\n> between HEAD and the index, and the index and the working tree file\n> (i.e. you earlier edited E and F, did \"git add E F\" and further\n> edited them).\n>\n> You say \"git commit -p F\".\n[...]\n>\n> What state should the \"add -p\" interaction start from for path F?\n> Should you be picking from a patch between the state you previously\n> \"git add\"ed to the index and the working tree, or should the entire\n> difference between HEAD and the working tree eligible to be picked\n> or deferred during the \"add -p\" session? Starting from a temporary\n> index that matches HEAD essentially means that you lose the earlier\n> \"git add F\" [*1*].\n\nTwo questions are easier answered:\n\nWhat should git commit --only --patch F do?\n=> It should start you from the state of HEAD.\n\nWhat should git commit --include --patch F do?\n=> It should start you from the state of the index.\n\nThe question that's harder to ponder, is \"what should the default be\".\nHistorically it's been '--include', but that was for the sake of easy\nimplementation (6cbf07efc5702351897dee4742525c9b9f7828ac). Using '--only' seems\ngood for consistency with other forms of git commit and the current\ndocumentation; inventing a third way (i.e. depending on which paths are\nspecified) seems worst of all.\n\nThe big UI problem with --only is not figuring out what should go in the commit,\nbut rather ensuring that the index is in the expected state after the commit\n(it's the problems solved by 2888605c649ccd423232161186d72c0e6c458a48 but for\nhunks instead of files). If file F has hunks (H, J, K) then I stage hunk J with\ngit add --interactive; then I commit hunks H & K with git commit --interactive,\nthe resulting index should contain H, J, K. Unfortunately, git add --interactive\nallows me to edit hunks, and so if I instead commit H & J2 (where J2 is an\nedited version of J) then the index would contain (H, J) and the commit (H, J2);\nthe working tree would contain H, J, K still.\n\nThis gets a bit mind-bending to resolve; the first solution I came up with\n\"don't touch the index if the index differs from HEAD\" will give unexpected\nresults in the case that extra non-conflicting chunks are added to the commit.\nThe next idea is to do a three-way merge between the new commit and the index\nwith the old HEAD as the base, and resolve conflicts in favour of the index. I\nthink that works, but it sounds pretty horrific to implement and still leaves\nyou in a pretty confusing state (though no more confusing than using edit in git\nadd --interactive normally is).\n\nThe other cases to consider are files that aren't in HEAD. At the moment git add\n --patch and git commit --patch cannot include new files, though that's fixable\nby treating new files as 1 hunk instead of 0.\n\nAll in all, I think supporting --only --interactive is well beyond what I'm\ncapable of doing, and probably pushing the limits of what's sane. (it would be\nnice for warm fuzzy completeness reasons though).\n\nOn Fri, Oct 5, 2012 at 3:57 PM, Jeff King wrote:\n> We should probably also support explicit \"-i -p\" and \"-o -p\" options, as\n> well (the former would give people who really want the existing behavior\n> a way to get it). And the same for \"--interactive\". I can't say I'm\n> excited about making all that work, though. Like you, I think it is more\n> sane to use existing tools to inspect and tweak the index to your\n> liking, and then commit.\n\nYou made the same thinko as me :). --include isn't defined to mean \"include the\nindex as well\", but rather \"include these files when committing the index\".\nFlipping that around makes a lot of sense and then --include can be used\nsemantically with --patch, --interactive or even --all. (patch attached).\n\n>\n> Unless somebody who cares about \"commit -p\" does so to come up with\n> reasonable semantics, and updates the code to match that desired\n> behaviour, the responsible thing to do is to error out \"-p\" when\n> your index is different from HEAD, I think.\n\nThat would be a shame; instead we should just document that \"--interactive\" and\n\"--patch\" add to the existing index like they always have. If we still worry\nabout users shooting themselves in the foot, then we can require \"--include\" to\nuse --interactive or --patch on a dirty index. (not done)\n\nConrad\n\n--------8<------\n\nFlip the meaning of 'git commit --include' from 'include these files' to\n'include the index' to reduce the number of concepts in the manpage.\n\nClarify that --interactive/--patch add to the existing index to avoid\nconfusion like [1].\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/207108\n\nSigned-off-by: Conrad Irwin \n---\n Documentation/git-commit.txt | 20 +++++++++++---------\n builtin/commit.c | 10 ++++++----\n 2 files changed, 17 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 9594ac8..a2d4a6d 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -41,9 +41,9 @@ The content to be added can be specified in several ways:\n actual commit;\n\n 5. by using the --interactive or --patch switches with the 'commit' command\n- to decide one by one which files or hunks should be part of the commit,\n- before finalizing the operation. See the ``Interactive Mode'' section of\n- linkgit:git-add[1] to learn how to operate these modes.\n+ to add files or hunks to the current index before committing. See the\n+ ``Interactive Mode'' section of linkgit:git-add[1] to learn how to\n+ operate these modes.\n\n The `--dry-run` option can be used to obtain a\n summary of what is included by any of the above for the next\n@@ -63,10 +63,14 @@ OPTIONS\n\n -p::\n --patch::\n- Use the interactive patch selection interface to chose\n- which changes to commit. See linkgit:git-add[1] for\n+ Use the interactive patch selection interface to add hunks\n+ to the index before committing. See linkgit:git-add[1] for\n details.\n\n+--interactive::\n+ Use the ``Interactive mode'' of linkgit:git-add[1] to edit\n+ the index before committing.\n+\n -C ::\n --reuse-message=::\n Take an existing commit object, and reuse the log message\n@@ -215,10 +219,8 @@ FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1].)\n\n -i::\n --include::\n- Before making a commit out of staged contents so far,\n- stage the contents of paths given on the command line\n- as well. This is usually not what you want unless you\n- are concluding a conflicted merge.\n+ In addition to the paths specified on the command line,\n+ include the current contents of the index in the commit.\n\n -o::\n --only::\ndiff --git a/builtin/commit.c b/builtin/commit.c\nindex a17a5df..14afa58 100644\n--- a/builtin/commit.c\n+++ b/builtin/commit.c\n@@ -1034,10 +1034,12 @@ static int parse_and_validate_options(int\nargc, const char *argv[],\n if (patch_interactive)\n interactive = 1;\n\n- if (!!also + !!only + !!all + !!interactive > 1)\n- die(_(\"Only one of\n--include/--only/--all/--interactive/--patch can be used.\"));\n- if (argc == 0 && (also || (only && !amend)))\n- die(_(\"No paths with --include/--only does not make sense.\"));\n+ if (only && all)\n+ die(_(\"--only with --all does not make sense.\"));\n+ if (only && interactive)\n+ die(_(\"--only with --interactive/--patch is not supported.\"));\n+ if (argc == 0 && (only && !amend))\n+ die(_(\"No paths with --only does not make sense.\"));\n if (argc == 0 && only && amend)\n only_include_assumed = _(\"Clever... amending the last\none with dirty index.\");\n if (argc > 0 && !also && !only)\n"},{"id":"200685","messageId":"20121006190753.GA5648@sigill.intra.peff.net","threadId":"31738","inReplyTo":"CAOTq_pu=xWF7q3QobxSerkkbV56n5o+CPQSyHg8onwv73v25+A@mail.gmail.com","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-06T19:07:53Z","receivedAt":"2012-10-06T19:07:53Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Oct 06, 2012 at 11:32:51AM -0700, Conrad Irwin wrote:\n\n> I think I messed up sending somehow:\n\nThanks for resending.\n\n> > What state should the \"add -p\" interaction start from for path F?\n> > Should you be picking from a patch between the state you previously\n> > \"git add\"ed to the index and the working tree, or should the entire\n> > difference between HEAD and the working tree eligible to be picked\n> > or deferred during the \"add -p\" session? Starting from a temporary\n> > index that matches HEAD essentially means that you lose the earlier\n> > \"git add F\" [*1*].\n> \n> Two questions are easier answered:\n> \n> What should git commit --only --patch F do?\n> => It should start you from the state of HEAD.\n\nAre you sure? Does \"--only\" mean \"only the changes I am about to mark\"\nor \"only the paths I am about to tell you about\"? Without partial hunk\nselection (i.e., \"commit -p\"), they were the same; a path you mention is\na path which will be either be staged in its entirety or not. Specifying\n(or omitting) the path was sufficient to say what you wanted. But with\n\"-p\", I can see three useful possibilities:\n\n 1. Do not include F in the commit, even if changes are staged in the\n index (i.e., take HEAD exactly).\n\n 2. Include F in the commit, and stage partial changes on top of what is\n already staged.\n\n 3. Include F in the commit, and stage partial changes on top of HEAD.\n\nIn cases 2 and 3, we are still taking \"only the path\" F. But we are\nnot taking \"only what is about to be staged\" in 2. And I can see both\nbeing useful (2 because it is more convenient not to re-approve staged\nchanges, and 3 because there is no way to unstage changes via \"-p\").\n\n> What should git commit --include --patch F do?\n> => It should start you from the state of the index.\n\nThis one is much easier. The distinction between cases 2 and 3 above\ndoes not exist here, because we always start from the current index\nstate.\n\nSo there are two questions:\n\n 1. How does --only interact with partial staging (whether paths are\n specified or not)?\n\n 2. What should the default for \"-p\" be, between \"--only\" and\n \"--include\"?\n\nI think the answer to the second is \"--only\"; but a prerequisite to that\nis making \"--only\" work at all (it currently just barfs). And a\nprerequisite to that is figuring out what the right semantics are.\n\n> The question that's harder to ponder, is \"what should the default be\".\n\nInterestingly, I came to the exact opposite conclusion of which question\nis harder. :)\n\n> The big UI problem with --only is not figuring out what should go in the commit,\n> but rather ensuring that the index is in the expected state after the commit\n> (it's the problems solved by 2888605c649ccd423232161186d72c0e6c458a48 but for\n> hunks instead of files). If file F has hunks (H, J, K) then I stage hunk J with\n> git add --interactive; then I commit hunks H & K with git commit --interactive,\n> the resulting index should contain H, J, K. Unfortunately, git add --interactive\n> allows me to edit hunks, and so if I instead commit H & J2 (where J2 is an\n> edited version of J) then the index would contain (H, J) and the commit (H, J2);\n> the working tree would contain H, J, K still.\n\nYeah, that's a gross-ness I hadn't even considered.\n\n> All in all, I think supporting --only --interactive is well beyond what I'm\n> capable of doing, and probably pushing the limits of what's sane. (it would be\n> nice for warm fuzzy completeness reasons though).\n\nYes. The more we talk about it, the more turned off I am by the idea.\nAbove I posed my questions as \"what _should_ we do when...\". And I still\nthink we _should_ default to --only with interactive, if we can find\nsane semantics. But until we can find them, it obviously does not make\nsense to enable it, and the whole discussion is stalled. And we must\ncome up with an interim solution that is the least bad.\n\nWhich is obviously one of:\n\n 1. Keep defaulting to \"--include\", as that is what we have been doing.\n\n 2. Forbid the cases where it would matter (i.e., when the index and\n HEAD differ).\n\nThe former is more convenient, but the latter is safer against future\nbreakage. I'm OK either way, but option (1) clearly needs a\ndocumentation update.\n\n> On Fri, Oct 5, 2012 at 3:57 PM, Jeff King wrote:\n> > We should probably also support explicit \"-i -p\" and \"-o -p\" options, as\n> > well (the former would give people who really want the existing behavior\n> > a way to get it). And the same for \"--interactive\". I can't say I'm\n> > excited about making all that work, though. Like you, I think it is more\n> > sane to use existing tools to inspect and tweak the index to your\n> > liking, and then commit.\n> \n> You made the same thinko as me :). --include isn't defined to mean \"include the\n> index as well\", but rather \"include these files when committing the index\".\n> Flipping that around makes a lot of sense and then --include can be used\n> semantically with --patch, --interactive or even --all. (patch attached).\n\nBut of course we're not specifying paths. So to me it is \"include the\nchanges I am about to stage via -p\", as opposed to \"--only use the\nchanges I am about to stage via -p\". I think the current behavior is\nmorally equivalent to how --include works with paths (which includes the\npaths along with the current index, rather than only committing the\npaths).\n\nOr am I missing something about the distinction you're making? It seems\nto me that the end behavior of thinking about it either way would be the\nsame.\n\n> --------8<------\n> \n> Flip the meaning of 'git commit --include' from 'include these files' to\n> 'include the index' to reduce the number of concepts in the manpage.\n> \n> Clarify that --interactive/--patch add to the existing index to avoid\n> confusion like [1].\n> \n> [1] http://thread.gmane.org/gmane.comp.version-control.git/207108\n\nThe documentation updates look like an improvement to me. Do we also\nneed a note about \"-p\" under \"-o\" where it says \"This is the default\nmode...\"?\n\n> diff --git a/builtin/commit.c b/builtin/commit.c\n> index a17a5df..14afa58 100644\n> --- a/builtin/commit.c\n> +++ b/builtin/commit.c\n> @@ -1034,10 +1034,12 @@ static int parse_and_validate_options(int\n> argc, const char *argv[],\n> if (patch_interactive)\n> interactive = 1;\n> \n> - if (!!also + !!only + !!all + !!interactive > 1)\n> - die(_(\"Only one of\n> --include/--only/--all/--interactive/--patch can be used.\"));\n> - if (argc == 0 && (also || (only && !amend)))\n> - die(_(\"No paths with --include/--only does not make sense.\"));\n> + if (only && all)\n> + die(_(\"--only with --all does not make sense.\"));\n> + if (only && interactive)\n> + die(_(\"--only with --interactive/--patch is not supported.\"));\n\nWe used to complain if (argc == 0 && also), but that seems to be lost\nhere. Wouldn't the new condition be (argc == 0 && also && !interactive)?\n\nWe also stopped complaining about \"also && all\", \"all && interactive\",\nand \"also && only\", all of which are nonsensical.\n\n> + if (argc == 0 && (only && !amend))\n> + die(_(\"No paths with --only does not make sense.\"));\n> if (argc == 0 && only && amend)\n> only_include_assumed = _(\"Clever... amending the last\n\nIt might be more readable to collapse these two conditionals to:\n\n if (argc == 0 && only) {\n \tif (!amend)\n\t\tdie(\"...does not make sense\");\n\tonly_include_assumed = \"Clever...\"\n }\n\nI wonder if it is even worth loosening this, though. The point, as I\nunderstand it, would be to allow \"-i -p\". But it doesn't actually do\nanything, does it (except, I suppose for allowing one to future-proof\ntheir script against a later change of the default to --only).\n\n-Peff\n"},{"id":"200712","messageId":"7vr4paovjq.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"20121006190753.GA5648@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-07T20:51:21Z","receivedAt":"2012-10-07T20:51:21Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Yes. The more we talk about it, the more turned off I am by the idea.\n> Above I posed my questions as \"what _should_ we do when...\". And I still\n> think we _should_ default to --only with interactive, if we can find\n> sane semantics. But until we can find them, it obviously does not make\n> sense to enable it, and the whole discussion is stalled. And we must\n> come up with an interim solution that is the least bad.\n>\n> Which is obviously one of:\n>\n> 1. Keep defaulting to \"--include\", as that is what we have been doing.\n>\n> 2. Forbid the cases where it would matter (i.e., when the index and\n> HEAD differ).\n>\n> The former is more convenient, but the latter is safer against\n> future breakage. I'm OK either way, but option (1) clearly needs a\n> documentation update.\n\nYeah, I agree with the reasoning. This is an unessential feature\nthat is with the problem for a long time, so let's go the route #1\nfirst before we do anything else.\n"},{"id":"200719","messageId":"20121007214958.GC1743@sigill.intra.peff.net","threadId":"31738","inReplyTo":"7vr4paovjq.fsf@alter.siamese.dyndns.org","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-07T21:49:58Z","receivedAt":"2012-10-07T21:49:58Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Oct 07, 2012 at 01:51:21PM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > Yes. The more we talk about it, the more turned off I am by the idea.\n> > Above I posed my questions as \"what _should_ we do when...\". And I still\n> > think we _should_ default to --only with interactive, if we can find\n> > sane semantics. But until we can find them, it obviously does not make\n> > sense to enable it, and the whole discussion is stalled. And we must\n> > come up with an interim solution that is the least bad.\n> >\n> > Which is obviously one of:\n> >\n> > 1. Keep defaulting to \"--include\", as that is what we have been doing.\n> >\n> > 2. Forbid the cases where it would matter (i.e., when the index and\n> > HEAD differ).\n> >\n> > The former is more convenient, but the latter is safer against\n> > future breakage. I'm OK either way, but option (1) clearly needs a\n> > documentation update.\n> \n> Yeah, I agree with the reasoning. This is an unessential feature\n> that is with the problem for a long time, so let's go the route #1\n> first before we do anything else.\n\nOK. I think Conrad's patch takes us most of the way there. I had a few\nminor comments, but I think another round should do it. Conrad?\n\n-Peff\n"},{"id":"200721","messageId":"7vehl9q5uk.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"20121007214958.GC1743@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-07T22:23:31Z","receivedAt":"2012-10-07T22:23:31Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Sun, Oct 07, 2012 at 01:51:21PM -0700, Junio C Hamano wrote:\n>\n>> Jeff King writes:\n>> \n>> > Which is obviously one of:\n>> >\n>> > 1. Keep defaulting to \"--include\", as that is what we have been doing.\n>> >\n>> > 2. Forbid the cases where it would matter (i.e., when the index and\n>> > HEAD differ).\n>> >\n>> > The former is more convenient, but the latter is safer against\n>> > future breakage. I'm OK either way, but option (1) clearly needs a\n>> > documentation update.\n>> \n>> Yeah, I agree with the reasoning. This is an unessential feature\n>> that is with the problem for a long time, so let's go the route #1\n>> first before we do anything else.\n>\n> OK. I think Conrad's patch takes us most of the way there. I had a few\n> minor comments, but I think another round should do it. Conrad?\n\nI'd rather want to see a patch that _only_ documents the current\nbehaviour to unconfuse people first. I definitely do not want any\npatch that changes the command line parsing or any other behaviour\nchange with problems that have to take time from reviewers to point\nthem out mixed in it.\n"},{"id":"200722","messageId":"20121007222502.GA3263@sigill.intra.peff.net","threadId":"31738","inReplyTo":"7vehl9q5uk.fsf@alter.siamese.dyndns.org","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-07T22:25:03Z","receivedAt":"2012-10-07T22:25:03Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Oct 07, 2012 at 03:23:31PM -0700, Junio C Hamano wrote:\n\n> >> Yeah, I agree with the reasoning. This is an unessential feature\n> >> that is with the problem for a long time, so let's go the route #1\n> >> first before we do anything else.\n> >\n> > OK. I think Conrad's patch takes us most of the way there. I had a few\n> > minor comments, but I think another round should do it. Conrad?\n> \n> I'd rather want to see a patch that _only_ documents the current\n> behaviour to unconfuse people first. I definitely do not want any\n> patch that changes the command line parsing or any other behaviour\n> change with problems that have to take time from reviewers to point\n> them out mixed in it.\n\nSorry, I should have been more clear. I want to see a re-roll of only\nthe documentation bits of Conrad's patch, for which I had only minor\ncomments. The code part had major problems. :)\n\n-Peff\n"},{"id":"200976","messageId":"CAOTq_ptaXMUzSi-PomMa9K9-Fnus0pnsO+vq92ZnxfeRQZPAxw@mail.gmail.com","threadId":"31738","inReplyTo":"20121007222502.GA3263@sigill.intra.peff.net","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Conrad Irwin","fromEmail":"conrad.irwin@gmail.com","sentAt":"2012-10-11T05:51:28Z","receivedAt":"2012-10-11T05:51:28Z","isPatch":false,"sender":{"key":"conrad.irwin@gmail.com","avatar":"https://avatars.githubusercontent.com/u/94272?v=4"},"body":"On Sat, Oct 6, 2012 at 12:07 PM, Jeff King wrote:\n> Are you sure? Does \"--only\" mean \"only the changes I am about to mark\"\n> or \"only the paths I am about to tell you about\"? Without partial hunk\n> selection (i.e., \"commit -p\"), they were the same; a path you mention is\n> a path which will be either be staged in its entirety or not. Specifying\n> (or omitting) the path was sufficient to say what you wanted. But with\n> \"-p\", I can see three useful possibilities:\n>\n> 1. Do not include F in the commit, even if changes are staged in the\n> index (i.e., take HEAD exactly).\n>\n> 2. Include F in the commit, and stage partial changes on top of what is\n> already staged.\n>\n> 3. Include F in the commit, and stage partial changes on top of HEAD.\n>\n> In cases 2 and 3, we are still taking \"only the path\" F. But we are\n> not taking \"only what is about to be staged\" in 2. And I can see both\n> being useful (2 because it is more convenient not to re-approve staged\n> changes, and 3 because there is no way to unstage changes via \"-p\").\n\nI think I didn't consider 2. as a viable alternative because\nre-approving hunks is not a problem (there are typically very few\nhunks per file, and you'll recognise them if you've already staged\nthem) but not being able to unstage is a big problem (as it restricts\nwhat commits I can make with --patch without changing my index).\n\n>\n> But of course we're not specifying paths. So to me it is \"include the\n> changes I am about to stage via -p\", as opposed to \"--only use the\n> changes I am about to stage via -p\". I think the current behavior is\n> morally equivalent to how --include works with paths (which includes the\n> paths along with the current index, rather than only committing the\n> paths).\n>\n> Or am I missing something about the distinction you're making? It seems\n> to me that the end behavior of thinking about it either way would be the\n> same.\n\nThe way I was thinking about it was to treat the index and the command\nline as two orthogonal parts of the commit. --include and --only\ncontrol the inclusion/exclusion of the index; while the command line\narguments control which (currently unstaged) things are included. This\nled me to the conclusion that \"git commit --include\" is equivalent to\n\"git commit\", \"git commit --include --all\" is the same as \"git commit\n--all\" which is why I tried to change the validation logic. (You are\ncorrect that \"--include --only\" and \"--interactive --all\" still make\nno sense).\n\nHere's a re-roll of the patch with --only docs tweaked.\n\nConrad\n\n----8<----\n\nClarify that --interactive/--patch add to the existing index to avoid\nconfusion like [1].\n\nMake explicit that --only does not work with --interactive/--patch and\nclean up wording around --only --amend.\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/207108\n\nSigned-off-by: Conrad Irwin \n---\n Documentation/git-commit.txt | 35 +++++++++++++++++------------------\n 1 file changed, 17 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 9594ac8..680d2bf 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -41,9 +41,9 @@ The content to be added can be specified in several ways:\n actual commit;\n\n 5. by using the --interactive or --patch switches with the 'commit' command\n- to decide one by one which files or hunks should be part of the commit,\n- before finalizing the operation. See the ``Interactive Mode'' section of\n- linkgit:git-add[1] to learn how to operate these modes.\n+ to add files or hunks to the current index before committing. See the\n+ ``Interactive Mode'' section of linkgit:git-add[1] to learn how to\n+ operate these modes.\n\n The `--dry-run` option can be used to obtain a\n summary of what is included by any of the above for the next\n@@ -63,10 +63,14 @@ OPTIONS\n\n -p::\n --patch::\n-\tUse the interactive patch selection interface to chose\n-\twhich changes to commit. See linkgit:git-add[1] for\n+\tUse the interactive patch selection interface to add hunks\n+\tto the index before committing. See linkgit:git-add[1] for\n \tdetails.\n\n+--interactive::\n+\tUse the ``Interactive mode'' of linkgit:git-add[1] to edit\n+\tthe index before committing.\n+\n -C ::\n --reuse-message=::\n \tTake an existing commit object, and reuse the log message\n@@ -215,22 +219,17 @@ FROM UPSTREAM REBASE\" section in linkgit:git-rebase[1].)\n\n -i::\n --include::\n-\tBefore making a commit out of staged contents so far,\n-\tstage the contents of paths given on the command line\n-\tas well. This is usually not what you want unless you\n-\tare concluding a conflicted merge.\n+\tIn addition to the paths specified on the command line,\n+\tinclude the current contents of the index in the commit.\n\n -o::\n --only::\n-\tMake a commit only from the paths specified on the\n-\tcommand line, disregarding any contents that have been\n-\tstaged so far. This is the default mode of operation of\n-\t'git commit' if any paths are given on the command line,\n-\tin which case this option can be omitted.\n-\tIf this option is specified together with '--amend', then\n-\tno paths need to be specified, which can be used to amend\n-\tthe last commit without committing changes that have\n-\talready been staged.\n+\tOnly commit changes to the paths specified on the command line,\n+\tdo not include the current contents of the index. This is\n+\tthe default mode of operation when paths are specified.\n+\tIf this option is specified with --amend it can be used\n+\tto reword the last commit without changing its contents.\n+\tThis mode cannot be used with --patch or --interactive.\n\n -u[]::\n --untracked-files[=]::\n-- \n1.7.12.289.g0ce9864\n"},{"id":"201010","messageId":"7vmwzs7uyh.fsf@alter.siamese.dyndns.org","threadId":"31738","inReplyTo":"CAOTq_ptaXMUzSi-PomMa9K9-Fnus0pnsO+vq92ZnxfeRQZPAxw@mail.gmail.com","subject":"Re: git 1.8.0.rc0.18.gf84667d trouble with \"git commit -p file\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-11T17:57:26Z","receivedAt":"2012-10-11T17:57:26Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Conrad Irwin writes:\n\n> -i::\n> --include::\n> -\tBefore making a commit out of staged contents so far,\n> -\tstage the contents of paths given on the command line\n> -\tas well. This is usually not what you want unless you\n> -\tare concluding a conflicted merge.\n> +\tIn addition to the paths specified on the command line,\n> +\tinclude the current contents of the index in the commit.\n\n\"commit\" is about committing what is in the index. include has\nalways meant \"in addition, include the contents of listed paths\nin the resulting commit\".\n\nThe updated text looks totally the other way around.\n\n> -o::\n> --only::\n> -\tMake a commit only from the paths specified on the\n> -\tcommand line, disregarding any contents that have been\n> -\tstaged so far. This is the default mode of operation of\n> -\t'git commit' if any paths are given on the command line,\n> -\tin which case this option can be omitted.\n> -\tIf this option is specified together with '--amend', then\n> -\tno paths need to be specified, which can be used to amend\n> -\tthe last commit without committing changes that have\n> -\talready been staged.\n> +\tOnly commit changes to the paths specified on the command line,\n> +\tdo not include the current contents of the index. This is\n> +\tthe default mode of operation when paths are specified.\n> +\tIf this option is specified with --amend it can be used\n> +\tto reword the last commit without changing its contents.\n> +\tThis mode cannot be used with --patch or --interactive.\n\nThe new text on this one does look cleaner and easier to read, at\nleast to me, but \"do not include the current contents\" sounds as if\nyou are recording a tree that only has Makefile and losing all the\nother files when you say \"git commit Makefile\".\n\n Disregard what has been added to the index since HEAD, and only\n commit changes to the given paths.\n\nmight be an improvement, but I dunno.\n"}]}