{"thread":{"id":"20792","subject":"[PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","startedAt":"2009-08-30T17:29:59Z","lastAt":"2009-09-15T10:35:04Z","messageCount":21,"participants":["Jari Aalto","Junio C Hamano","Jeff King","Mikael Magnusson","Sean Estabrooks","Nanako Shiraishi"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"122121","messageId":"87ocpxb46g.fsf@jondo.cante.net","threadId":"20792","inReplyTo":null,"subject":"[PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-30T17:29:59Z","receivedAt":"2009-08-30T17:29:59Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"\nSigned-off-by: Jari Aalto \n---\n Documentation/git-add.txt | 10 +++++-----\n 1 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e67b7e8..71990c2 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -67,14 +67,14 @@ OPTIONS\n --interactive::\n \tAdd modified contents in the working tree interactively to\n \tthe index. Optional path arguments may be supplied to limit\n-\toperation to a subset of the working tree. See ``Interactive\n-\tmode'' for details.\n+\toperation to a subset of the working tree. See section\n+\t``INTERACTIVE MODE'' for details.\n \n -p::\n --patch::\n-\tSimilar to Interactive mode but the initial command loop is\n-\tbypassed and the 'patch' subcommand is invoked using each of\n-\tthe specified filepatterns before exiting.\n+\tRun interactive patch command for each file on command line.\n+\tSee section INTERACTIVE MODE and patch subcommand for more\n+\tinformation.\n \n -e, \\--edit::\n \tOpen the diff vs. the index in an editor and let the user\n-- \n1.6.3.3\n"},{"id":"122130","messageId":"7vab1hdppb.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"87ocpxb46g.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-30T20:14:24Z","receivedAt":"2009-08-30T20:14:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-add.txt | 10 +++++-----\n> 1 files changed, 5 insertions(+), 5 deletions(-)\n>\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index e67b7e8..71990c2 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -67,14 +67,14 @@ OPTIONS\n> --interactive::\n> \tAdd modified contents in the working tree interactively to\n> \tthe index. Optional path arguments may be supplied to limit\n> -\toperation to a subset of the working tree. See ``Interactive\n> -\tmode'' for details.\n> +\toperation to a subset of the working tree. See section\n> +\t``INTERACTIVE MODE'' for details.\n\nSorry, the change in this hunk does not make *any* sense to me.\n\nIt is not justified with your commit log message, I do not see why you\nhave to shout in all CAPS, and there is no such section in the\ndocumentation. But the \"Interactive mode\" section exists and is referred\nto by the original.\n\n> -p::\n> --patch::\n> -\tSimilar to Interactive mode but the initial command loop is\n> -\tbypassed and the 'patch' subcommand is invoked using each of\n> -\tthe specified filepatterns before exiting.\n> +\tRun interactive patch command for each file on command line.\n> +\tSee section INTERACTIVE MODE and patch subcommand for more\n> +\tinformation.\n\nI personally think fixing misworded phrase \"initial command loop\" would be\nsufficient. It should read \"initial command menu\". Perhaps like this.\n\n\tRun ``add --interactive``, but bypass the initial command menu and\n\tdirectly jump to `patch` subcommand. See ``Interactive mode'' for\n\tdetails.\n\nIf you assume that the reader is not familiar with \"add -i\", then the\nabove is not descriptive enough, but \"Run interactive patch command\" is\nnot an improvement either. We would need a description of \"what it is\nused for\" before \"how it would look to you\" (i.e.. my rewrite shown\nabove).\n\n\"What it is used for\" would perhaps read like this.\n\n\tReview the difference between the index and the work tree, and add\n\tmodified contents to the index interactively by choosing which\n\tpatch hunks to use.\n"},{"id":"122137","messageId":"20090830210231.GA4471@coredump.intra.peff.net","threadId":"20792","inReplyTo":"7vab1hdppb.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2009-08-30T21:02:31Z","receivedAt":"2009-08-30T21:02:31Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Aug 30, 2009 at 01:14:24PM -0700, Junio C Hamano wrote:\n\n> > -\toperation to a subset of the working tree. See ``Interactive\n> > -\tmode'' for details.\n> > +\toperation to a subset of the working tree. See section\n> > +\t``INTERACTIVE MODE'' for details.\n> \n> Sorry, the change in this hunk does not make *any* sense to me.\n> \n> It is not justified with your commit log message, I do not see why you\n> have to shout in all CAPS, and there is no such section in the\n> documentation. But the \"Interactive mode\" section exists and is referred\n> to by the original.\n\nI think it is an attempt to match the way docbook renders manpage\nheadings; it converts headings to all-caps. And there is some precedent;\ntry grepping for \".EXAMPLES\" in Documentation/*.txt.\n\nThat being said, the straight asciidoc->html version leaves the\ncapitalization untouched. However, that actually makes the html version\nlook quite awkward. Some of the headings are in all-caps and some are\nnot. So I wonder if we should make them typographically consistent.\n\n(And yes, I totally agree that this hunk was a surprise after reading\nthe commit message and if anything is done, it should be in a separate\npatch).\n\n-Peff\n"},{"id":"122143","messageId":"87tyzp9da4.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"7vab1hdppb.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-30T21:56:19Z","receivedAt":"2009-08-30T21:56:19Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n> Jari Aalto writes:\n>\n>> Signed-off-by: Jari Aalto \n>> ---\n>> Documentation/git-add.txt | 10 +++++-----\n>> 1 files changed, 5 insertions(+), 5 deletions(-)\n>>\n>> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n>> index e67b7e8..71990c2 100644\n>> --- a/Documentation/git-add.txt\n>> +++ b/Documentation/git-add.txt\n>> @@ -67,14 +67,14 @@ OPTIONS\n>> --interactive::\n>> \tAdd modified contents in the working tree interactively to\n>> \tthe index. Optional path arguments may be supplied to limit\n>> -\toperation to a subset of the working tree. See ``Interactive\n>> -\tmode'' for details.\n>> +\toperation to a subset of the working tree. See section\n>> +\t``INTERACTIVE MODE'' for details.\n>\n> It is not justified with your commit log message, I do not see why you\n> have to shout in all CAPS, and there is no such section in the\n> documentation. But the \"Interactive mode\" section exists and is referred\n> to by the original.\n\nIt is not shouting, but standard practise to refer to manual page\nsection in ALL CAPS, when they are top level headings, like in this\ncase.\n\n>> -p::\n>> --patch::\n>> -\tSimilar to Interactive mode but the initial command loop is\n>> -\tbypassed and the 'patch' subcommand is invoked using each of\n>> -\tthe specified filepatterns before exiting.\n>> +\tRun interactive patch command for each file on command line.\n>> +\tSee section INTERACTIVE MODE and patch subcommand for more\n>> +\tinformation.\n>\n> I personally think fixing misworded phrase \"initial command loop\" would be\n> sufficient. It should read \"initial command menu\". Perhaps like this.\n>\n> \tRun ``add --interactive``, but bypass the initial command menu and\n> \tdirectly jump to `patch` subcommand. See ``Interactive mode'' for\n> \tdetails.\n\nIt's still too technical. The 1st line should go right into business:\n\n \tPatch each file on command line interactively. This is this is\n \tthe same as ``add --interactive``, but bypass the initial\n \tcommand menu and directly jump to `patch` subcommand. See\n \t``Interactive mode'' for details.\n\nJari\n"},{"id":"122144","messageId":"87prad9d2n.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"7vab1hdppb.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-30T22:00:48Z","receivedAt":"2009-08-30T22:00:48Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n>> +\toperation to a subset of the working tree. See section\n>> +\t``INTERACTIVE MODE'' for details.\n>\n> It is not justified with your commit log message, I do not see why you\n> have to shout in all CAPS, \n\nThere are plenty of examples, that it's standard practise to refer top\nlevel headings, in all caps, from:\n\n POSIX/SusV guides for manual pages: \"1.11 Utility Description Defaults\"\n http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n\nJari\n"},{"id":"122145","messageId":"7vskf954sr.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"87tyzp9da4.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-30T22:13:08Z","receivedAt":"2009-08-30T22:13:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> It is not shouting, but standard practise to refer to manual page\n> section in ALL CAPS, when they are top level headings, like in this\n> case.\n\nWhy are you making excuses, ignoring the fact that you didn't have a\nmatching update to make the section also in caps in the patch?\n\nSections that are common in all manual pages (e.g. NAME, SYNOPSIS,\nDESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in\ncaps. You do not have to explain that to me ;-)\n\nIf you wanted to add \"Interactive mode\" to that set of \"common sections\"\nand spell it in caps, do so consistently.\n\nSee http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode\nfor what I mean.\n\n>> I personally think fixing misworded phrase \"initial command loop\" would be\n>> sufficient. It should read \"initial command menu\". Perhaps like this.\n>>\n>> \tRun ``add --interactive``, but bypass the initial command menu and\n>> \tdirectly jump to `patch` subcommand. See ``Interactive mode'' for\n>> \tdetails.\n>\n> It's still too technical. The 1st line should go right into business:\n>\n> \tPatch each file on command line interactively. This is this is\n> \tthe same as ``add --interactive``, but bypass the initial\n> \tcommand menu and directly jump to `patch` subcommand. See\n> \t``Interactive mode'' for details.\n\nEven if we ignore the double \"this is this is\", I do not think it is\nbetter than the original.\n\nWhat does \"Patch each file\" mean? When read naively (and that is the\nwhole point of your \"too technical\" comment), a reader would expect there\nwill be changes made _to_ the work tree files.\n\nIf you want to start the description with \"What it does/what it is used\nfor\", I think it is a good idea. I already made a suggestion for such an\nimprovement in my message you are responding to.\n\nIf you want to make a counterproposal, at least please do that with a\ncounter-proposal that is better.\n"},{"id":"122148","messageId":"87ab1gaol2.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"7vskf954sr.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-30T23:06:49Z","receivedAt":"2009-08-30T23:06:49Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n> Sections that are common in all manual pages (e.g. NAME, SYNOPSIS,\n> DESCRIPTION, EXAMPLES, SEE ALSO) are often spelled in and referred to in\n> caps. \n\nNot just common ones. All sections that are top level heading are best\nspelled out consistently. Examples can be found from the URL to\nPOSIX/Susv in my other post.\n\n[I'll get back to the CAPS patch in anaother post if we can sort this out]\n\n> See http://www.kernel.org/pub/software/scm/git/docs/git-add.html#_interactive_mode\n> for what I mean.\n\nI think the convention used in git's manual pages deviate from the\nstandard practise. We could make the git manual pages into line of:\n\n- write all the first level headings in all caps: \"HEADING LIKE THIS\"\n- write second level heading: start Upper-lower: \"Heading like this\"\n\nCf. rsync(1), ssh(1) etc. many pages prior git's existense.\n\n>>> I personally think fixing misworded phrase \"initial command loop\" would be\n>>> sufficient. It should read \"initial command menu\". Perhaps like this.\n>>>\n>>> \tRun ``add --interactive``, but bypass the initial command menu and\n>>> \tdirectly jump to `patch` subcommand. See ``Interactive mode'' for\n>>> \tdetails.\n>>\n>> It's still too technical. The 1st line should go right into business:\n>>\n>> \tPatch each file on command line interactively. This is this is\n>> \tthe same as ``add --interactive``, but bypass the initial\n>> \tcommand menu and directly jump to `patch` subcommand. See\n>> \t``Interactive mode'' for details.\n>\n> I do not think it is better than the original.\n\nYour proposal that starts:\n\n ...but bypass the initial command menu\n\nMine:\n\n Patch each file on command line interactively\n\nThe first line should somehow strike immediately what the command does.\nI would like to see a suggestion that has 'patch(ing)' somewhere at the\nvery first row. I hope we can find compromise.\n\nJari\n"},{"id":"122149","messageId":"7vbplw28js.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"87ab1gaol2.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-30T23:20:23Z","receivedAt":"2009-08-30T23:20:23Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> Your proposal that starts:\n>\n> ...but bypass the initial command menu\n\nNo, it doesn't..\n\nGo re-read the message you are responding to, paying extra attention to\nthe parts you snipped from your quote, which was the important part you\nshould have read before you responded.\n\n If you want to start the description with \"What it does/what it is used\n for\", I think it is a good idea. I already made a suggestion for such an\n improvement in my message you are responding to.\n\nNow, what was that suggestion?\n\nIt is in the message your first response was a follow-up to. Again you\ndidn't quote the relevant part in that response, and perhaps that was\nbecause you did not even read it before responding.\n\n If you assume that the reader is not familiar with \"add -i\", then the\n above is not descriptive enough, but \"Run interactive patch command\" is\n not an improvement either. We would need a description of \"what it is\n used for\" before \"how it would look to you\" (i.e.. my rewrite shown\n above).\n\n \"What it is used for\" would perhaps read like this.\n\n Review the difference between the index and the work tree, and add\n modified contents to the index interactively by choosing which\n patch hunks to use.\n\nThis time I re-quoted things for you because your responses obviously were\nwritten without reading or understanding them, but please be careful not\nto make me do this. I do not have infinite time.\n"},{"id":"122150","messageId":"7vr5usyj3i.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"87ab1gaol2.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-30T23:31:29Z","receivedAt":"2009-08-30T23:31:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> I think the convention used in git's manual pages deviate from the\n> standard practise. We could make the git manual pages into line of:\n>\n> - write all the first level headings in all caps: \"HEADING LIKE THIS\"\n> - write second level heading: start Upper-lower: \"Heading like this\"\n>\n> Cf. rsync(1), ssh(1) etc. many pages prior git's existense.\n\nHaving seen that nothing happened after a separate thread that was also on\nthe documentation consistency:\n\n http://thread.gmane.org/gmane.comp.version-control.git/72163/focus=72213\n\nI am having a hard time to decide how seriously I should take the above\ncomment from you.\n\nAre you volunteering to coordinate such a change (in other words, you do\nnot necessarily have to do _all_ the work yourself, alone), or is it just\nan idle speculation?\n"},{"id":"122168","messageId":"873a78a2dc.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"7vr5usyj3i.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-31T07:06:39Z","receivedAt":"2009-08-31T07:06:39Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n> Jari Aalto writes:\n>\n>> I think the convention used in git's manual pages deviate from the\n>> standard practise. We could make the git manual pages into line of:\n>>\n>> - write all the first level headings in all caps: \"HEADING LIKE THIS\"\n>> - write second level heading: start Upper-lower: \"Heading like this\"\n>>\n>> Cf. rsync(1), ssh(1) etc. many pages prior git's existense.\n>\n\n[URL: That's a separate issue. The resolution hung in the air how to\nproceed]\n\nPlease be patient. I understand that you have lot work. I do care,\ntherefore I take the time to suggest some chnages.\n\n> Are you volunteering to coordinate such a change (in other words, you do\n> not necessarily have to do _all_ the work yourself, alone)\n\nWe need resolution first. What would you think about that change?\n\nI could offer patches, but not in any time frame to do it in one-swoop\ndo-it-all patch. To distribute time and effort to do so, it would be\nsensible to handle one manual at a time. The whole work would eventually\nget done.\n\nThere could be section in TODO.\n\n RFH - Request for help: Manual page adjustments\n\n - If you have some spare time, the following manual pages adjustment\n is needed for all git manuals ....\n\nOr 2-weekly RFH post could announce the need. That would be one way to\ncoordinate participants.\n\nJari\n"},{"id":"122169","messageId":"7v8wh04ewk.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"873a78a2dc.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-31T07:32:27Z","receivedAt":"2009-08-31T07:32:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> I could offer patches, but not in any time frame to do it in one-swoop\n> do-it-all patch. To distribute time and effort to do so, it would be\n> sensible to handle one manual at a time. The whole work would eventually\n> get done.\n\nYeah, that's the spirit, and that is why I said you do not necessarily\nhave to do all the work yourself. It would be expected of that volunteer\nto keep an eye on patches other helpful folks may send to cover the issue,\nvet them to make sure they do not introduce silly typos, AsciiDoc\nbreakages, and needless conflicts.\n\nAs to guidelines, I think your \"spell all top-level headlines in caps\" is\na reasonable one, as \"man\" backend for AsciiDoc does that anyway.\n\nFor the ancient \"Synopsis\" issue, SD5-XCU-ERN-97 would be a reasonable\nguideline to follow (http://www.opengroup.org/austin/docs/austin_325.txt).\n\n> There could be section in TODO.\n>\n> RFH - Request for help: Manual page adjustments\n>\n> - If you have some spare time, the following manual pages adjustment\n> is needed for all git manuals ....\n>\n> Or 2-weekly RFH post could announce the need. That would be one way to\n> coordinate participants.\n\nI would leave such a procedural issue to the volunteer who heads the\neffort to decide. If you are asking me to decide, then you are not\nvolunteering yourself, but you are volunteering _me_ for the job ;-).\n\nThanks.\n"},{"id":"122171","messageId":"87y6p08lz5.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"7vbplw28js.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-08-31T07:46:06Z","receivedAt":"2009-08-31T07:46:06Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\nI apologize if you though I did not read. I did, but I the separate\nparagraph order did not meet here as you might have intended.\n\nTo recap, your suggestion, if read correct:\n\n --patch:\n -p::\n Review the difference between the index and the work tree, and add\n modified contents to the index interactively by choosing which\n patch hunks to use.\n\n Run ``add --interactive``, but bypass the initial command menu and\n directly jump to `patch` subcommand. See ``Interactive mode'' for\n details.\n\nFor more direct first line, howabout:\n\n --patch:\n -p::\n In a modified work tree, choose interactively which patch hunks to\n add. This gives a change to review the difference between the\n index and the work before adding modified contents to the index.\n\n This effectively runs ``add --interactive``, but bypass the\n initial command menu and directly jump to `patch` subcommand.\n See ``Interactive mode'' for details.\n\nJari\n"},{"id":"122212","messageId":"7vmy5fy2hz.fsf@alter.siamese.dyndns.org","threadId":"20792","inReplyTo":"87y6p08lz5.fsf@jondo.cante.net","subject":"Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-08-31T23:42:16Z","receivedAt":"2009-08-31T23:42:16Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto writes:\n\n> --patch:\n> -p::\n> In a modified work tree, choose interactively which patch hunks to\n> add. This gives a change to review the difference between the\n> index and the work before adding modified contents to the index.\n\nSounds sensible. You may want to be even more direct and succinct, e.g.\n\n Interactively choose hunks of patch between the index and the work\n tree and add them to the index.\n"},{"id":"123035","messageId":"87ab0zny27.fsf_-_@jondo.cante.net","threadId":"20792","inReplyTo":"7vmy5fy2hz.fsf@alter.siamese.dyndns.org","subject":"[PATCH] Improve --patch option documentation in git-add","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-09-13T06:44:32Z","receivedAt":"2009-09-13T06:44:32Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Junio C Hamano writes:\n\n> Jari Aalto writes:\n>\n>> --patch:\n>> -p::\n>> In a modified work tree, choose interactively which patch hunks to\n>> add. This gives a change to review the difference between the\n>> index and the work before adding modified contents to the index.\n>\n> Sounds sensible. You may want to be even more direct and succinct, e.g.\n>\n> Interactively choose hunks of patch between the index and the work\n> tree and add them to the index.\n\nThanks, see below,\nJari\n\n>From 63aa94e7782d6340ead0446ea80ed6223d7ac5c1 Mon Sep 17 00:00:00 2001\nFrom: Jari Aalto \nDate: Sun, 13 Sep 2009 09:43:10 +0300\nSubject: [PATCH] Improve --patch option documentation in git-add\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-add.txt | 11 ++++++++---\n 1 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e67b7e8..b94fbec 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -72,9 +72,14 @@ OPTIONS\n \n -p::\n --patch::\n-\tSimilar to Interactive mode but the initial command loop is\n-\tbypassed and the 'patch' subcommand is invoked using each of\n-\tthe specified filepatterns before exiting.\n+\tInteractively choose hunks of patch between the index and the\n+\twork tree and add them to the index. This gives a change to\n+\treview the difference before adding modified contents to the\n+\tindex.\n+\n+\tThis effectively runs ``add --interactive``, but bypass the\n+\tinitial command menu and directly jump to `patch` subcommand.\n+\tSee ``Interactive mode'' for details.\n \n -e, \\--edit::\n \tOpen the diff vs. the index in an editor and let the user\n-- \n1.6.3.3\n"},{"id":"123057","messageId":"237967ef0909130648l36b592aft9c50ccff5d03d1b1@mail.gmail.com","threadId":"20792","inReplyTo":"87ab0zny27.fsf_-_@jondo.cante.net","subject":"Re: [PATCH] Improve --patch option documentation in git-add","fromName":"Mikael Magnusson","fromEmail":"mikachu@gmail.com","sentAt":"2009-09-13T13:48:40Z","receivedAt":"2009-09-13T13:48:40Z","isPatch":true,"sender":{"key":"mikachu@gmail.com","avatar":null},"body":"2009/9/13 Jari Aalto :\n> Junio C Hamano writes:\n>\n>> Jari Aalto writes:\n>>\n>>> --patch:\n>>> -p::\n>>> In a modified work tree, choose interactively which patch hunks to\n>>> add. This gives a change to review the difference between the\n>>> index and the work before adding modified contents to the index.\n>>\n>> Sounds sensible. You may want to be even more direct and succinct, e.g.\n>>\n>> Interactively choose hunks of patch between the index and the work\n>> tree and add them to the index.\n>\n> Thanks, see below,\n> Jari\n>\n> From 63aa94e7782d6340ead0446ea80ed6223d7ac5c1 Mon Sep 17 00:00:00 2001\n> From: Jari Aalto \n> Date: Sun, 13 Sep 2009 09:43:10 +0300\n> Subject: [PATCH] Improve --patch option documentation in git-add\n>\n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-add.txt | 11 ++++++++---\n> 1 files changed, 8 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index e67b7e8..b94fbec 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -72,9 +72,14 @@ OPTIONS\n>\n> -p::\n> --patch::\n> - Similar to Interactive mode but the initial command loop is\n> - bypassed and the 'patch' subcommand is invoked using each of\n> - the specified filepatterns before exiting.\n> + Interactively choose hunks of patch between the index and the\ndiff probably makes more sense than patch here\n\n> + work tree and add them to the index. This gives a change to\na chance\n\n> + review the difference before adding modified contents to the\ndifferences? Not sure which I prefer on this one.\n\n> + index.\n> +\n> + This effectively runs ``add --interactive``, but bypass the\nbypasses\n\n> + initial command menu and directly jump to `patch` subcommand.\njumps\n\n> + See ``Interactive mode'' for details.\n>\n> -e, \\--edit::\n> Open the diff vs. the index in an editor and let the user\n> --\n> 1.6.3.3\n\n-- \nMikael Magnusson\n"},{"id":"123058","messageId":"87vdjnlywo.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"237967ef0909130648l36b592aft9c50ccff5d03d1b1@mail.gmail.com","subject":"Re: [PATCH] Improve --patch option documentation in git-add","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-09-13T14:09:11Z","receivedAt":"2009-09-13T14:09:11Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Mikael Magnusson writes:\n>> + Interactively choose hunks of patch between the index and the\n> diff probably makes more sense than patch here\n>\n>> + work tree and add them to the index. This gives a change to\n> a chance\n>\n>> + review the difference before adding modified contents to the\n> differences? Not sure which I prefer on this one.\n>\n>> + index.\n>> +\n>> + This effectively runs ``add --interactive``, but bypass the\n> bypasses\n>\n>> + initial command menu and directly jump to `patch` subcommand.\n> jumps\n\nAn update. Thanks,\nJari\n\n\n\n>From beca0d3dcd668e1b578588378149320cd3aed9d9 Mon Sep 17 00:00:00 2001\nFrom: Jari Aalto \nDate: Sun, 13 Sep 2009 17:08:51 +0300\nSubject: [PATCH] Improve --patch option documentation in git-add\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-add.txt | 11 ++++++++---\n 1 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e67b7e8..0b2a2a6 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -72,9 +72,14 @@ OPTIONS\n \n -p::\n --patch::\n-\tSimilar to Interactive mode but the initial command loop is\n-\tbypassed and the 'patch' subcommand is invoked using each of\n-\tthe specified filepatterns before exiting.\n+\tInteractively choose hunks of diff between the index and the\n+\twork tree and add them to the index. This gives a change to\n+\treview the differences before adding modified contents to the\n+\tindex.\n+\n+\tThis effectively runs ``add --interactive``, but bypass the\n+\tinitial command menu and directly jumps to `patch` subcommand.\n+\tSee ``Interactive mode'' for details.\n \n -e, \\--edit::\n \tOpen the diff vs. the index in an editor and let the user\n-- \n1.6.3.3\n\n"},{"id":"123171","messageId":"BLU0-SMTP18292B09CCFD873F4A6DF6AEE40@phx.gbl","threadId":"20792","inReplyTo":"87vdjnlywo.fsf@jondo.cante.net","subject":"Re: [PATCH] Improve --patch option documentation in git-add","fromName":"Sean Estabrooks","fromEmail":"seanlkml@sympatico.ca","sentAt":"2009-09-14T13:13:16Z","receivedAt":"2009-09-14T13:13:16Z","isPatch":true,"sender":{"key":"seanlkml@sympatico.ca","avatar":"https://gravatar.com/avatar/f92923f54fc08c401fc59b71829d4b89e9b8087fbba45ff87c82e6a83aee02ae?d=mp&s=160"},"body":"On Sun, 13 Sep 2009 17:09:11 +0300\nJari Aalto wrote:\n\n> An update. Thanks,\n> Jari\n> \n[...]\n> -p::\n> --patch::\n> -\tSimilar to Interactive mode but the initial command loop is\n> -\tbypassed and the 'patch' subcommand is invoked using each of\n> -\tthe specified filepatterns before exiting.\n> +\tInteractively choose hunks of diff between the index and the\n> +\twork tree and add them to the index. This gives a change to\n> +\treview the differences before adding modified contents to the\n> +\tindex.\n> +\n> +\tThis effectively runs ``add --interactive``, but bypass the\n> +\tinitial command menu and directly jumps to `patch` subcommand.\n> +\tSee ``Interactive mode'' for details.\n\n\nJari,\n\nIt's good that you're working to make the documentation better. To\nme though, it seems more difficult to parse this description than the\none offered by Junio in an earlier thread:\n\n Review the difference between the index and the work tree, and add\n modified contents to the index interactively by choosing which\n patch hunks to use. \n\nIf you don't want to just use that description verbatim, perhaps you'd\nconsider something closer to yours, such as:\n\n\tInteractively review the differences between the index and the\n\twork tree and choose which hunks to add into the index.\n\n\tThis effectively runs ``add --interactive``, but bypasses the\n\tinitial command menu and jumps directly to the `patch` subcommand.\n\tSee ``Interactive mode'' for details.\n\nCheers,\nSean\n"},{"id":"123205","messageId":"87fxaolqhd.fsf_-_@jondo.cante.net","threadId":"20792","inReplyTo":"BLU0-SMTP18292B09CCFD873F4A6DF6AEE40@phx.gbl","subject":"Re: [PATCH] Improve --patch option documentation in git-add (updated patch)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-09-15T05:35:42Z","receivedAt":"2009-09-15T05:35:42Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Sean Estabrooks writes:\n> ... To me though, it seems more difficult to parse this description\n> than the one offered by Junio in an earlier thread ...perhaps you'd\n> consider something closer to yours, such as:\n>\n> \tInteractively review the differences between the index and the\n> \twork tree and choose which hunks to add into the index.\n>\n> \tThis effectively runs ``add --interactive``, but bypasses the\n> \tinitial command menu and jumps directly to the `patch` subcommand.\n> \tSee ``Interactive mode'' for details.\n\n\nUpdated, thanks,\nJari\n\n\n\n>From be5eebc53c2e3dcf67edfb371d8aa8263e1a8d69 Mon Sep 17 00:00:00 2001\nFrom: Jari Aalto \nDate: Tue, 15 Sep 2009 08:33:51 +0300\nSubject: [PATCH] Improve --patch option documentation in git-add\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-add.txt | 9 ++++++---\n 1 files changed, 6 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex e67b7e8..c57895a 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -72,9 +72,12 @@ OPTIONS\n \n -p::\n --patch::\n-\tSimilar to Interactive mode but the initial command loop is\n-\tbypassed and the 'patch' subcommand is invoked using each of\n-\tthe specified filepatterns before exiting.\n+\tInteractively review the differences between the index and the\n+\twork tree and choose which hunks to add into the index.\n+\n+\tThis effectively runs ``add --interactive``, but bypasses the\n+\tinitial command menu and jumps directly to the `patch` subcommand.\n+\tSee ``Interactive mode'' for details.\n \n -e, \\--edit::\n \tOpen the diff vs. the index in an editor and let the user\n-- \n1.6.3.3\n\n"},{"id":"123213","messageId":"20090915155208.6117@nanako3.lavabit.com","threadId":"20792","inReplyTo":"87fxaolqhd.fsf_-_@jondo.cante.net","subject":"Re: [PATCH] Improve --patch option documentation in git-add (updated patch)","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-09-15T06:52:08Z","receivedAt":"2009-09-15T06:52:08Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Jari Aalto \n\n> Sean Estabrooks writes:\n>> ... To me though, it seems more difficult to parse this description\n>> than the one offered by Junio in an earlier thread ...perhaps you'd\n>> consider something closer to yours, such as:\n>>\n>> \tInteractively review the differences between the index and the\n>> \twork tree and choose which hunks to add into the index.\n>>\n>> \tThis effectively runs ``add --interactive``, but bypasses the\n>> \tinitial command menu and jumps directly to the `patch` subcommand.\n>> \tSee ``Interactive mode'' for details.\n>\n>\n> Updated, thanks,\n> Jari\n>\n>\n> From be5eebc53c2e3dcf67edfb371d8aa8263e1a8d69 Mon Sep 17 00:00:00 2001\n> From: Jari Aalto \n> Date: Tue, 15 Sep 2009 08:33:51 +0300\n> Subject: [PATCH] Improve --patch option documentation in git-add\n>\n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-add.txt | 9 ++++++---\n> 1 files changed, 6 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\n> index e67b7e8..c57895a 100644\n> --- a/Documentation/git-add.txt\n> +++ b/Documentation/git-add.txt\n> @@ -72,9 +72,12 @@ OPTIONS\n> \n> -p::\n> --patch::\n> -\tSimilar to Interactive mode but the initial command loop is\n> -\tbypassed and the 'patch' subcommand is invoked using each of\n> -\tthe specified filepatterns before exiting.\n> +\tInteractively review the differences between the index and the\n> +\twork tree and choose which hunks to add into the index.\n> +\n> +\tThis effectively runs ``add --interactive``, but bypasses the\n> +\tinitial command menu and jumps directly to the `patch` subcommand.\n> +\tSee ``Interactive mode'' for details.\n> \n> -e, \\--edit::\n> \tOpen the diff vs. the index in an editor and let the user\n\nSorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"},{"id":"299119","messageId":"87tyz4k4eg.fsf@jondo.cante.net","threadId":"20792","inReplyTo":"20090915155208.6117@nanako3.lavabit.com","subject":"Re: [PATCH] Improve --patch option documentation in git-add (updated patch)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2009-09-15T08:17:59Z","receivedAt":"2009-09-15T08:17:59Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Nanako Shiraishi writes:\n\n> Sorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?\n\nJunio merged the patch at 5f2b1e6\n\nJari\n"},{"id":"123220","messageId":"20090915193504.6117@nanako3.lavabit.com","threadId":"20792","inReplyTo":"87tyz4k4eg.fsf@jondo.cante.net","subject":"Re: [PATCH] Improve --patch option documentation in git-add (updated patch)","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-09-15T10:35:04Z","receivedAt":"2009-09-15T10:35:04Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Jari Aalto \n\n> Nanako Shiraishi writes:\n>\n>> Sorry, but this patch doesn't seem to apply anywhere. Have you fetched recently?\n>\n> Junio merged the patch at 5f2b1e6\n\nOh, I see.\n\nIf so, could you rebase and resend?\n\nIt would also be nicer if you followed Documentation/SubmittingPatches when composing your message, writing any additional comments after the three dashes line.\n\nThank you.\n\n-- \nNanako Shiraishi\nhttp://ivory.ap.teacup.com/nanako3/\n"}]}