{"thread":{"id":"23480","subject":"[PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","startedAt":"2010-04-15T15:37:03Z","lastAt":"2010-04-17T18:46:24Z","messageCount":6,"participants":["jari.aalto@cante.net","Michael J Gruber","Jari Aalto","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"139600","messageId":"1271345823-19685-1-git-send-email-jari.aalto@cante.net","threadId":"23480","inReplyTo":null,"subject":"[PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"","fromEmail":"jari.aalto@cante.net","sentAt":"2010-04-15T15:37:03Z","receivedAt":"2010-04-15T15:37:03Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"From: Jari Aalto \n\n\nSigned-off-by: Jari Aalto \n---\n Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++--\n 1 files changed, 34 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex ced35b2..8b33eb0 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -299,8 +299,40 @@ sendemail.confirm::\n \tone of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'\n \tin the previous section for the meaning of these values.\n \n+EXAMPLES\n+--------\n \n-Author\n+To batch send all patches to a mailig list, no copies to oneself,\n+messages in a relaxed single thread format (no nesting) and don't ask\n+any confirmations:\n+\n+\tgit send-email \\\n+\t\t--from $EMAIL \\\n+\t\t--to address@list.example.com \\\n+\t\t--suppress-cc=author \\\n+\t\t--suppress-from \\\n+\t\t--no-chain-reply-to \\\n+\t\t--confirm=never \\\n+\t\toutgoing/\n+\n+Tip: in case the patches in a branch need rework, you might consider\n+adjusting the subjects of each patch to \"[PATCH v]\" with\n+options '--subject-prefix'. The 'merge-base' inside command\n+substitution is there to find out the initial commit of the branch:\n+\n+\tgit checkout BRANCH\n+\n+\tgit format-patch \\\n+\t\t--subject-prefix=\"PATCH v2\" \\\n+\t\t--signoff \\\n+\t\t-M \\\n+\t\t--output-directory outgoing/\n+\t\t$(git merge-base HEAD master)..\n+\n+Then proceed as in in the first example the send the patches out\n+again.\n+\n+AUTHOR\n ------\n Written by Ryan Anderson \n \n@@ -308,7 +340,7 @@ git-send-email is originally based upon\n send_lots_of_email.pl by Greg Kroah-Hartman.\n \n \n-Documentation\n+DOCUMENTATION\n --------------\n Documentation by Ryan Anderson\n \n-- \n1.7.0\n"},{"id":"139658","messageId":"4BC81975.9000907@drmicha.warpmail.net","threadId":"23480","inReplyTo":"1271345823-19685-1-git-send-email-jari.aalto@cante.net","subject":"Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-04-16T08:01:57Z","receivedAt":"2010-04-16T08:01:57Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"jari.aalto@cante.net venit, vidit, dixit 15.04.2010 17:37:\n> From: Jari Aalto \n> \n> \n> Signed-off-by: Jari Aalto \n> ---\n> Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++--\n> 1 files changed, 34 insertions(+), 2 deletions(-)\n> \n> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n> index ced35b2..8b33eb0 100644\n> --- a/Documentation/git-send-email.txt\n> +++ b/Documentation/git-send-email.txt\n> @@ -299,8 +299,40 @@ sendemail.confirm::\n> \tone of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'\n> \tin the previous section for the meaning of these values.\n> \n> +EXAMPLES\n> +--------\n> \n> -Author\n> +To batch send all patches to a mailig list, no copies to oneself,\n> +messages in a relaxed single thread format (no nesting) and don't ask\n> +any confirmations:\n\nThat sentence is linguistically screwed, but...\n\n> +\n> +\tgit send-email \\\n> +\t\t--from $EMAIL \\\n> +\t\t--to address@list.example.com \\\n> +\t\t--suppress-cc=author \\\n> +\t\t--suppress-from \\\n> +\t\t--no-chain-reply-to \\\n> +\t\t--confirm=never \\\n> +\t\toutgoing/\n> +\n\n... I don't think this is a good example at all. All options are\nexplained in the man page, so what is the point in listing and\nexplaining some of them here? If we really want an introductory example,\nwe want one with few options, where the default behaviour is explained.\n\n> +Tip: in case the patches in a branch need rework, you might consider\n> +adjusting the subjects of each patch to \"[PATCH v]\" with\n> +options '--subject-prefix'. \n\nThat is a git.git convention, and it applies to format-patch, not\nsend-email.\n\n> The 'merge-base' inside command\n> +substitution is there to find out the initial commit of the branch:\n> +\n> +\tgit checkout BRANCH\n> +\n> +\tgit format-patch \\\n> +\t\t--subject-prefix=\"PATCH v2\" \\\n> +\t\t--signoff \\\n> +\t\t-M \\\n> +\t\t--output-directory outgoing/\n> +\t\t$(git merge-base HEAD master)..\n> +\n\nThis is a useful example (although it mixes several issues), but one for\nformat-patch, not send-email. You assume you branched off master. Using\n@{upstream} might be a more general option.\n\n> +Then proceed as in in the first example the send the patches out\n> +again.\n> +\n> +AUTHOR\n> ------\n> Written by Ryan Anderson \n> \n> @@ -308,7 +340,7 @@ git-send-email is originally based upon\n> send_lots_of_email.pl by Greg Kroah-Hartman.\n> \n> \n> -Documentation\n> +DOCUMENTATION\n> --------------\n> Documentation by Ryan Anderson\n> \n"},{"id":"139663","messageId":"8739yvsjqv.fsf@jondo.cante.net","threadId":"23480","inReplyTo":"4BC81975.9000907@drmicha.warpmail.net","subject":"Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-04-16T11:46:16Z","receivedAt":"2010-04-16T11:46:16Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Michael J Gruber writes:\n\n> jari.aalto@cante.net venit, vidit, dixit 15.04.2010 17:37:\n>\n>> From: Jari Aalto \n>> \n>> \n>> Signed-off-by: Jari Aalto \n>> ---\n>> Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++--\n>> 1 files changed, 34 insertions(+), 2 deletions(-)\n>> \n>> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n>> index ced35b2..8b33eb0 100644\n>> --- a/Documentation/git-send-email.txt\n>> +++ b/Documentation/git-send-email.txt\n>> @@ -299,8 +299,40 @@ sendemail.confirm::\n>> \tone of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'\n>> \tin the previous section for the meaning of these values.\n>> \n>> +EXAMPLES\n>> +--------\n>> \n>> -Author\n>> +To batch send all patches to a mailig list, no copies to oneself,\n>> +messages in a relaxed single thread format (no nesting) and don't ask\n>> +any confirmations:\n>\n> That sentence is linguistically screwed, but...\n\nPlease improve. How would you explain the options and their explanations\none-by-one as presented below?\n\n>> +\n>> +\tgit send-email \\\n>> +\t\t--from $EMAIL \\\n>> +\t\t--to address@list.example.com \\\n>> +\t\t--suppress-cc=author \\\n>> +\t\t--suppress-from \\\n>> +\t\t--no-chain-reply-to \\\n>> +\t\t--confirm=never \\\n>> +\t\toutgoing/\n>> +\n>\n> ... I don't think this is a good example at all. All options are\n> explained in the man page, so what is the point in listing and\n> explaining some of them here?\n\nRight, all the 31 options.\n\n> If we really want an introductory example,\n> we want one with few options, where the default behaviour is explained.\n\nI don't agree.\n\nWe need examples that use most of the options in combination so that the\nexamples can practically \"copy pasted / sliced off\". The user can eaily\nreduce options he may not find useful from the examples.\n\n With too few options presented, he needs to skim through the whole\n of 31 option explanations above and pray he finds what he needs.\n\nPlease suggest another example to be accompanied with this one. How do\nyou use the git-send-email? What options? What you have configured in\n~/.gitconfig?\n\nJari\n"},{"id":"139665","messageId":"4BC8605F.5070306@drmicha.warpmail.net","threadId":"23480","inReplyTo":"8739yvsjqv.fsf@jondo.cante.net","subject":"Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2010-04-16T13:04:31Z","receivedAt":"2010-04-16T13:04:31Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jari Aalto venit, vidit, dixit 16.04.2010 13:46:\n> Michael J Gruber writes:\n> \n>> jari.aalto@cante.net venit, vidit, dixit 15.04.2010 17:37:\n>>\n>>> From: Jari Aalto \n>>>\n>>>\n>>> Signed-off-by: Jari Aalto \n>>> ---\n>>> Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++--\n>>> 1 files changed, 34 insertions(+), 2 deletions(-)\n>>>\n>>> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n>>> index ced35b2..8b33eb0 100644\n>>> --- a/Documentation/git-send-email.txt\n>>> +++ b/Documentation/git-send-email.txt\n>>> @@ -299,8 +299,40 @@ sendemail.confirm::\n>>> \tone of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'\n>>> \tin the previous section for the meaning of these values.\n>>> \n>>> +EXAMPLES\n>>> +--------\n>>> \n>>> -Author\n>>> +To batch send all patches to a mailig list, no copies to oneself,\n>>> +messages in a relaxed single thread format (no nesting) and don't ask\n>>> +any confirmations:\n>>\n>> That sentence is linguistically screwed, but...\n> \n> Please improve. How would you explain the options and their explanations\n> one-by-one as presented below?\n\nBy \"but...\" and the paragraph below I meant to say that there is no need\nto pick on individual typos and such, because I don't favour the\napproach anyways.\n\nLooking at the send-email man page, I definitely agree with you that\nthere is room for improvement. For example, in the end there is a\nconfiguration section listing only very few of the config options. The\nreader could easily think these are the only ones. We tend to list them\nin git-config's man page, which one may or may not like...\n\n> \n>>> +\n>>> +\tgit send-email \\\n>>> +\t\t--from $EMAIL \\\n>>> +\t\t--to address@list.example.com \\\n>>> +\t\t--suppress-cc=author \\\n>>> +\t\t--suppress-from \\\n>>> +\t\t--no-chain-reply-to \\\n>>> +\t\t--confirm=never \\\n>>> +\t\toutgoing/\n>>> +\n>>\n>> ... I don't think this is a good example at all. All options are\n>> explained in the man page, so what is the point in listing and\n>> explaining some of them here?\n> \n> Right, all the 31 options.\n> \n>> If we really want an introductory example,\n>> we want one with few options, where the default behaviour is explained.\n> \n> I don't agree.\n> \n> We need examples that use most of the options in combination so that the\n> examples can practically \"copy pasted / sliced off\". The user can eaily\n> reduce options he may not find useful from the examples.\n> \n> With too few options presented, he needs to skim through the whole\n> of 31 option explanations above and pray he finds what he needs.\n> \n> Please suggest another example to be accompanied with this one. How do\n> you use the git-send-email? What options? What you have configured in\n> ~/.gitconfig?\n\nI don't use any options besides --dry-run and --cc, which is the point\nof the config options ;) In config I have to, smtpserver (pointing to an\nmsmtp-script), bcc, suppresscc, aliasesfile, aliastype, but that depends\non the project, of course (git.git here).\n\nI just think that using all these options on the command line is very\natypical. It would be helpful to see the defaults in one place:\n\n\"Without any options, send-email will send patches (using\n/usr/sbin/sendmail or /usr/lib/sendmail or localhost) using any from, cc\nand subject lines contained in the patch files; you have to specify at\nleast --to, or else you will be prompted for it.\n\nAll defaults pertaining to composing and sending of the patch mails and\nto automating this process can be changed with config options, see the\ncorresponding sections below.\"\n\nI liked your format-patch example with merge-base, I just liked it\nbetter in format-patch's man page ;)\n\nMichael\n"},{"id":"139689","messageId":"87eiifqqdr.fsf@jondo.cante.net","threadId":"23480","inReplyTo":"4BC8605F.5070306@drmicha.warpmail.net","subject":"Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2010-04-16T17:05:52Z","receivedAt":"2010-04-16T17:05:52Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Michael J Gruber writes:\n\n> I just think that using all these options on the command line is very\n> atypical. It would be helpful to see the defaults in one place:\n\nNow, think this:\n\n You have 30 servers.\n\n You notice a problem.\n\n You need that command, whatever that is.\n\n Consult manual page, yay (Wow, or \"Ugh\")\n\n there is EXMAPLE, options and - Hurray: Copy/Paste and use.\n\nYou don't necessarily have full blown \"environment\" in front of you, so\nwe need both\n\n * Full command line exmaples. They are commadn line options after\n all\n * And configuration examples\n\nThe more copy/paste ready, the better. The more FAQ like, the better.\nLet's make FAQs obsolete.\n\nThansk for the examples, I'll be revising the patch\nJari\n"},{"id":"139771","messageId":"7viq7pzzlr.fsf@alter.siamese.dyndns.org","threadId":"23480","inReplyTo":"4BC8605F.5070306@drmicha.warpmail.net","subject":"Re: [PATCH] git-send-email.txt: Add EXAMPLES section. Write 1st level sections in uppercase","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-04-17T18:46:24Z","receivedAt":"2010-04-17T18:46:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> I don't use any options besides --dry-run and --cc, which is the point\n> of the config options ;) In config I have to, smtpserver (pointing to an\n> msmtp-script), bcc, suppresscc, aliasesfile, aliastype, but that depends\n> on the project, of course (git.git here).\n>\n> I just think that using all these options on the command line is very\n> atypical.\n\nHaving to give too many options from the command line all the time is a\nsure sign that the defaults for unconfigured case are bad (which may well\nbe true but is is hard to change without a good plan) and that it is not\nclearly explained how to configure the defaults for the repository.\n\nI do not think it is productive to give an overwhelming list that you\nwould rarely use (i.e. until you figure out a good set of defaults for the\nproject).\n\n> \"Without any options, send-email will send patches (using\n> /usr/sbin/sendmail or /usr/lib/sendmail or localhost) using any from, cc\n> and subject lines contained in the patch files; you have to specify at\n> least --to, or else you will be prompted for it.\n>\n> All defaults pertaining to composing and sending of the patch mails and\n> to automating this process can be changed with config options, see the\n> corresponding sections below.\"\n\nYes, I think we should proceed in this direction.\n\n> I liked your format-patch example with merge-base, I just liked it\n> better in format-patch's man page ;)\n\nLikewise.\n"}]}