{"thread":{"id":"39899","subject":"[PATCH 1/3] doc: convert send-email option headings to nouns","startedAt":"2015-07-20T18:26:26Z","lastAt":"2015-07-22T18:58:50Z","messageCount":18,"participants":["Philip Oakley","Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"266509","messageId":"1437416790-5792-1-git-send-email-philipoakley@iee.org","threadId":"39899","inReplyTo":null,"subject":"[PATCH 0/3] Update send-email cc-cmd documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:26:26Z","receivedAt":"2015-07-20T18:26:26Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This mini series updates captures the details of how to use the\ncc-cmd option of send-email, following my abortive attempts to\nuse a simple 'cat cc-cmd' invocation.\n\nThe alternative text for 'auto-cc' has been somewhat guesses at.\n\nI haven't tested how well it lays out when docbook'ed.\n\nThe series could be squashed together..\n\nPhilip Oakley (3):\n doc: convert send-email option headings to nouns\n doc: send-email; expand on the meaning of 'auto-cc'\n doc: give examples for send-email cc-cmd operation\n\n Documentation/git-send-email.txt | 54 +++++++++++++++++++++++++++++++++-------\n 1 file changed, 45 insertions(+), 9 deletions(-)\n\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"266506","messageId":"1437416790-5792-2-git-send-email-philipoakley@iee.org","threadId":"39899","inReplyTo":"1437416790-5792-1-git-send-email-philipoakley@iee.org","subject":"[PATCH 1/3] doc: convert send-email option headings to nouns","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:26:27Z","receivedAt":"2015-07-20T18:26:27Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"... for ease of reference within the text.\n\nExcept the 'Sending options' for which there wasn't an\nobvious noun phrase.\n\nSigned-off-by: Philip Oakley \n---\n Documentation/git-send-email.txt | 16 ++++++++--------\n 1 file changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 7ae467b..bc357b8 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -41,8 +41,8 @@ and the \"Subject:\" of the message as the second line.\n OPTIONS\n -------\n \n-Composing\n-~~~~~~~~~\n+Composition options\n+~~~~~~~~~~~~~~~~~~~\n \n --annotate::\n \tReview and edit each patch you're about to send. Default is the value\n@@ -147,8 +147,8 @@ Note that no attempts whatsoever are made to validate the encoding.\n \tthe header is added, but it can be turned off by setting the\n \t`sendemail.xmailer` configuration variable to `false`.\n \n-Sending\n-~~~~~~~\n+Sending options\n+~~~~~~~~~~~~~~~\n \n --envelope-sender=
::\n \tSpecify the envelope sender used to send the emails.\n@@ -234,8 +234,8 @@ must be used for each option.\n \tcommands and replies will be printed. Useful to debug TLS\n \tconnection and authentication problems.\n \n-Automating\n-~~~~~~~~~~\n+Automation options\n+~~~~~~~~~~~~~~~~~~\n \n --to-cmd=::\n \tSpecify a command to execute once per patch file which\n@@ -326,8 +326,8 @@ Failure to do so may not produce the expected result in the\n recipient's MUA.\n \n \n-Administering\n-~~~~~~~~~~~~~\n+Administration options\n+~~~~~~~~~~~~~~~~~~~~~~\n \n --confirm=::\n \tConfirm just before sending:\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"266510","messageId":"1437416790-5792-3-git-send-email-philipoakley@iee.org","threadId":"39899","inReplyTo":"1437416790-5792-1-git-send-email-philipoakley@iee.org","subject":"[PATCH 2/3] doc: send-email; expand on the meaning of 'auto-cc'","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:26:28Z","receivedAt":"2015-07-20T18:26:28Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/git-send-email.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex bc357b8..ddc8a11 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -282,7 +282,7 @@ Automation options\n \n --suppress-cc=::\n \tSpecify an additional category of recipients to suppress the\n-\tauto-cc of:\n+\tinclusion of addresses added via other automation options:\n +\n --\n - 'author' will avoid including the patch author\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"266508","messageId":"1437416790-5792-4-git-send-email-philipoakley@iee.org","threadId":"39899","inReplyTo":"1437416790-5792-1-git-send-email-philipoakley@iee.org","subject":"[PATCH 2/3] doc: send-email; expand oon the meaning of 'auto-cc'","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:26:29Z","receivedAt":"2015-07-20T18:26:29Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Signed-off-by: Philip Oakley \n---\n Documentation/git-send-email.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex bc357b8..ddc8a11 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -282,7 +282,7 @@ Automation options\n \n --suppress-cc=::\n \tSpecify an additional category of recipients to suppress the\n-\tauto-cc of:\n+\tinclusion of addresses added via other automation options:\n +\n --\n - 'author' will avoid including the patch author\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"266507","messageId":"1437416790-5792-5-git-send-email-philipoakley@iee.org","threadId":"39899","inReplyTo":"1437416790-5792-1-git-send-email-philipoakley@iee.org","subject":"[PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:26:30Z","receivedAt":"2015-07-20T18:26:30Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Explain how the cc-cmd (and to-cmd) is invoked, along with two\nsimple examples (and a how-not-to example) to help in getting started.\n\nHelped-by: Eric Sunshine \nSigned-off-by: Philip Oakley \n---\nhttp://article.gmane.org/gmane.comp.version-control.git/274302\n---\n Documentation/git-send-email.txt | 36 ++++++++++++++++++++++++++++++++++++\n 1 file changed, 36 insertions(+)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex ddc8a11..9f991cf 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -436,6 +436,42 @@ following commands:\n Note: the following perl modules are required\n Net::SMTP::SSL, MIME::Base64 and Authen::SASL\n \n+Creating a cc-cmd (and to-cmd) action\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+git-send-email invokes the cc-cmd like this:\n+\n+\t$cc-cmd $patchfilename\n+\n+Thus the patch itself can be processed to locate appropriate email address\n+information if required.\n+\n+A simple solution for a basic address list is to create a 'cc-cmd' file\n+(executable) which provides a list of addressees:\n+\n+\t#!/bin/sh\n+\techo <<\\EOF\n+\tperson1@example.com\n+\tperson2@example.com\n+\tEOF\n+\n+Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file\n+of email addresses), does not work as expected as the invocation becomes:\n+\n+\t$cat cc-cmd $patchfilename\n+\n+and since 'cat' copies the concatenation of its input files to its output,\n+this adds the patch file to the address list resulting in an error\n+\"unable to extract a valid address from:\".\n+\n+The quick-and-dirty work-around is to use '#' to effectively comment out\n+the patch file name:\n+\n+ --cc-cmd='cat cc-cmd #'\n+\n+which works, but is very, very ugly.\n+\n+\n SEE ALSO\n --------\n linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)\n-- \n2.4.2.windows.1.5.gd32afb6\n"},{"id":"266511","messageId":"CAPig+cQ7y0wdAEhUGS6piGWs=qEFQ2cXCFcFSD1dcnpbBppQ0g@mail.gmail.com","threadId":"39899","inReplyTo":"1437416790-5792-3-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH 2/3] doc: send-email; expand on the meaning of 'auto-cc'","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-20T18:34:05Z","receivedAt":"2015-07-20T18:34:05Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jul 20, 2015 at 2:26 PM, Philip Oakley wrote:\n> doc: send-email; expand on the meaning of 'auto-cc'\n\ns/;/:/\n\n> Signed-off-by: Philip Oakley \n> ---\n> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n> index bc357b8..ddc8a11 100644\n> --- a/Documentation/git-send-email.txt\n> +++ b/Documentation/git-send-email.txt\n> @@ -282,7 +282,7 @@ Automation options\n>\n> --suppress-cc=::\n> Specify an additional category of recipients to suppress the\n> - auto-cc of:\n> + inclusion of addresses added via other automation options:\n> +\n> --\n> - 'author' will avoid including the patch author\n> --\n> 2.4.2.windows.1.5.gd32afb6\n"},{"id":"266512","messageId":"CAPig+cQ_G=Ar0uxbxDaO6oEZwkRi7FM4qEQexDohDGxN10OJUA@mail.gmail.com","threadId":"39899","inReplyTo":"1437416790-5792-5-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-20T18:50:06Z","receivedAt":"2015-07-20T18:50:06Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jul 20, 2015 at 2:26 PM, Philip Oakley wrote:\n> Explain how the cc-cmd (and to-cmd) is invoked, along with two\n> simple examples (and a how-not-to example) to help in getting started.\n>\n> Helped-by: Eric Sunshine \n> Signed-off-by: Philip Oakley \n> ---\n> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n> index ddc8a11..9f991cf 100644\n> --- a/Documentation/git-send-email.txt\n> +++ b/Documentation/git-send-email.txt\n> @@ -436,6 +436,42 @@ following commands:\n> Note: the following perl modules are required\n> Net::SMTP::SSL, MIME::Base64 and Authen::SASL\n>\n> +Creating a cc-cmd (and to-cmd) action\n> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n> +\n> +git-send-email invokes the cc-cmd like this:\n> +\n> + $cc-cmd $patchfilename\n> +\n> +Thus the patch itself can be processed to locate appropriate email address\n> +information if required.\n> +\n> +A simple solution for a basic address list is to create a 'cc-cmd' file\n> +(executable) which provides a list of addressees:\n\nRather than calling this a \"simple solution\", you might instead say\nthat this is an example of a bare-bones script which just returns a\nfixed list of email addresses without attempting to extract any\naddresses from the patch file itself.\n\n> + #!/bin/sh\n> + echo <<\\EOF\n> + person1@example.com\n> + person2@example.com\n> + EOF\n\nI don't know if it deserves mention that the script must be executable\n(chmod +x) or should we assume that readers are smart enough to\nunderstand this implicitly? (It probably should be mentioned.)\n\nOther than those minor points, the above looks fine, however...\n\n> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file\n> +of email addresses), does not work as expected as the invocation becomes:\n> +\n> + $cat cc-cmd $patchfilename\n> +\n> +and since 'cat' copies the concatenation of its input files to its output,\n> +this adds the patch file to the address list resulting in an error\n> +\"unable to extract a valid address from:\".\n> +\n> +The quick-and-dirty work-around is to use '#' to effectively comment out\n> +the patch file name:\n> +\n> + --cc-cmd='cat cc-cmd #'\n> +\n> +which works, but is very, very ugly.\n\nThis entire above text about \"cat $addressfile\" seems awfully\ninappropriate for a manual page, especially the bit about the terrible\n\"cat $file #\" hack.\n\n> SEE ALSO\n> --------\n> linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)\n> --\n> 2.4.2.windows.1.5.gd32afb6\n>\n"},{"id":"266513","messageId":"B9C93EEED9F74E15B696C41494B6DBF9@PhilipOakley","threadId":"39899","inReplyTo":"1437416790-5792-4-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH 2/3] doc: send-email; expand oon the meaning of 'auto-cc'","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T18:55:50Z","receivedAt":"2015-07-20T18:55:50Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"This one, with \"oon\" in the subject, is incorrect.\n\nI made the same mistake yesterday, thinking that a fresh format-patch \nhad/would over-write the previous patches, but I'd forgot, again, that \nthe filename uses the subject line, so send-email picked up both \nversions .. doh.\n\nSorry for the noise.\n----- Original Message ----- \n> From: \"Philip Oakley\" \n> To: \"Git List\" \n> Cc: \"Junio C Hamano\" ; \"Eric Sunshine\" \n> \n> Sent: Monday, July 20, 2015 7:26 PM\n> Subject: [PATCH 2/3] doc: send-email; expand oon the meaning of \n> 'auto-cc'\n"},{"id":"266514","messageId":"CAPig+cQ2nTt60iw0Td_MTP7xftt2+OQAx63pOZ4XzH0qeOhDsA@mail.gmail.com","threadId":"39899","inReplyTo":"CAPig+cQ_G=Ar0uxbxDaO6oEZwkRi7FM4qEQexDohDGxN10OJUA@mail.gmail.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-20T19:14:41Z","receivedAt":"2015-07-20T19:14:41Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jul 20, 2015 at 2:50 PM, Eric Sunshine wrote:\n> On Mon, Jul 20, 2015 at 2:26 PM, Philip Oakley wrote:\n>> Explain how the cc-cmd (and to-cmd) is invoked, along with two\n>> simple examples (and a how-not-to example) to help in getting started.\n>>\n>> Helped-by: Eric Sunshine \n>> Signed-off-by: Philip Oakley \n>> ---\n>> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file\n>> +of email addresses), does not work as expected as the invocation becomes:\n>> +\n>> + $cat cc-cmd $patchfilename\n>> +\n>> +and since 'cat' copies the concatenation of its input files to its output,\n>> +this adds the patch file to the address list resulting in an error\n>> +\"unable to extract a valid address from:\".\n>> +\n>> +The quick-and-dirty work-around is to use '#' to effectively comment out\n>> +the patch file name:\n>> +\n>> + --cc-cmd='cat cc-cmd #'\n>> +\n>> +which works, but is very, very ugly.\n>\n> This entire above text about \"cat $addressfile\" seems awfully\n> inappropriate for a manual page, especially the bit about the terrible\n> \"cat $file #\" hack.\n\nIf you really want to give an example of how to use --cc-cmd\n(--to-cmd) with a plain text file holding email addresses, maybe\nsomething like this instead:\n\nCreate an EXAMPLES section.\n\nMake the bare-bones, static address list script the first example:\n\n #!/bin/sh\n echo <<\\EOF\n person1@example.com\n person2@example.com\n EOF\n\nThen add an example showing how to take the fixed address list from a\nplain text file. Have the user create the following script (let's call\nit \"anticat\") which cat's all of its input arguments except the final\none, which is the patch itself:\n\n #!/bin/sh\n while test $# -gt 1\n do\n cat $1\n shift\n done\n\nAnd, to use: --to-cccmd='anticat myaddresses.txt'\n"},{"id":"266515","messageId":"1E307B9A21744983970834F69116F358@PhilipOakley","threadId":"39899","inReplyTo":"CAPig+cQ_G=Ar0uxbxDaO6oEZwkRi7FM4qEQexDohDGxN10OJUA@mail.gmail.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T19:36:36Z","receivedAt":"2015-07-20T19:36:36Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Eric Sunshine\" \n> On Mon, Jul 20, 2015 at 2:26 PM, Philip Oakley \n> wrote:\n>> Explain how the cc-cmd (and to-cmd) is invoked, along with two\n>> simple examples (and a how-not-to example) to help in getting \n>> started.\n>>\n>> Helped-by: Eric Sunshine \n>> Signed-off-by: Philip Oakley \n>> ---\n>> diff --git a/Documentation/git-send-email.txt \n>> b/Documentation/git-send-email.txt\n>> index ddc8a11..9f991cf 100644\n>> --- a/Documentation/git-send-email.txt\n>> +++ b/Documentation/git-send-email.txt\n>> @@ -436,6 +436,42 @@ following commands:\n>> Note: the following perl modules are required\n>> Net::SMTP::SSL, MIME::Base64 and Authen::SASL\n>>\n>> +Creating a cc-cmd (and to-cmd) action\n>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n>> +\n>> +git-send-email invokes the cc-cmd like this:\n>> +\n>> + $cc-cmd $patchfilename\n>> +\n>> +Thus the patch itself can be processed to locate appropriate email \n>> address\n>> +information if required.\n>> +\n>> +A simple solution for a basic address list is to create a 'cc-cmd' \n>> file\n>> +(executable) which provides a list of addressees:\n>\n> Rather than calling this a \"simple solution\", you might instead say\n> that this is an example of a bare-bones script which just returns a\n> fixed list of email addresses without attempting to extract any\n> addresses from the patch file itself.\n>\n>> + #!/bin/sh\n>> + echo <<\\EOF\n>> + person1@example.com\n>> + person2@example.com\n>> + EOF\n>\n> I don't know if it deserves mention that the script must be executable\n> (chmod +x) or should we assume that readers are smart enough to\n> understand this implicitly? (It probably should be mentioned.)\n\nIt's there, but it's after the wrap-around. Maybe\ns/(executable)/(must be executable: `chmod +x`)/\nto be fully pedantic.\n\n>\n> Other than those minor points, the above looks fine, however...\n>\n>> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text \n>> file\n>> +of email addresses), does not work as expected as the invocation \n>> becomes:\n>> +\n>> + $cat cc-cmd $patchfilename\n>> +\n>> +and since 'cat' copies the concatenation of its input files to its \n>> output,\n>> +this adds the patch file to the address list resulting in an error\n>> +\"unable to extract a valid address from:\".\n>> +\n>> +The quick-and-dirty work-around is to use '#' to effectively comment \n>> out\n>> +the patch file name:\n>> +\n>> + --cc-cmd='cat cc-cmd #'\n>> +\n>> +which works, but is very, very ugly.\n>\n> This entire above text about \"cat $addressfile\" seems awfully\n> inappropriate for a manual page, especially the bit about the terrible\n> \"cat $file #\" hack.\n\nGiven that this invocation is why this all kicked off ...\n'cat list.txt', being the most simple of commands and a first cargo-cult \ntry for many, I definitely think it's worthwhile including somehow.\n\nPerhaps one needs to be more direct with the right invocation.\n\n\"A simple `--cc-cmd='cat list.txt #'` is a quick-and-dirty way of using \nan address list, while ignoring the patch content.\"\n\n\n>\n>> SEE ALSO\n>> --------\n>> linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)\n>> --\n>> 2.4.2.windows.1.5.gd32afb6\n>>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n> \n"},{"id":"266516","messageId":"xmqqoaj6y50b.fsf@gitster.dls.corp.google.com","threadId":"39899","inReplyTo":"1437416790-5792-5-git-send-email-philipoakley@iee.org","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-20T19:59:32Z","receivedAt":"2015-07-20T19:59:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> +git-send-email invokes the cc-cmd like this:\n> +\n> +\t$cc-cmd $patchfilename\n> +\n> +Thus the patch itself can be processed to locate appropriate email address\n> +information if required.\n\nThat's not even a valid command line (cc-cmd cannot be a shell\nvariable name), so why bother writing it that way? Rather\n\n The program that is specified by `cc-cmd` is invoked by `git\n send-email` with the name of the patch file as an argument;\n the program can read from it and customize its output based on\n what the patch file contains.\n \nor something like that, perhaps.\n\n> +\n> +A simple solution for a basic address list is to create a 'cc-cmd' file\n> +(executable) which provides a list of addressees:\n\nThere is no \"problem\" stated here that requires your \"solution\". In\nfact, what problem are you solving?\n\n> +\t#!/bin/sh\n> +\techo <<\\EOF\n> +\tperson1@example.com\n> +\tperson2@example.com\n> +\tEOF\n\nThat is one simple and denegerate use case; if the program does not\nneed any information from the patch file, it surely has an option\nnot to look at it. But it is not an interesting usage.\n\nIf you want to add a single example to illustrate how cc-cmd (or\nto-cmd, or anything that goes thru recipients_cmd()), you should\nhave an example that reads the input and then adds a few hardcoded\none.\n\n\t#!/bin/sh\n\t# always send it to the logger service\n echo \"patchlog@example.com\"\n\t# tell the bug tracker as necessary\n\tif fixes=$(sed -ne 's/^Fixes bug#\\([0-9]*\\)/\\1/p' \"$1\")\n then\n\t\techo \"bugs+$fixes@example.com\"\n\tfi\n\nor something silly like that.\n\nAnd this ...\n\n> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text file\n> +of email addresses), does not work as expected as the invocation becomes:\n> +\n> +\t$cat cc-cmd $patchfilename\n> +\n\n... and the rest of the patch is unnecessary noise to a reader who\nread that the single argument to the program is the name of the\npatchfile, I think. You were trying to avoid the same confusion\ncaused by the sketchy documentaiton, and you already \"solved\" that\nproblem by telling the reader what the command takes as its input.\n\n> + --cc-cmd='cat cc-cmd #'\n\nThis heavily depends on the current implementation that happens to\npass the command line string to a shell.\n"},{"id":"266517","messageId":"CAPig+cTJ3uKhSbvPKen7UQxoqVx3ZOET9k-8w73igTbrQB5iig@mail.gmail.com","threadId":"39899","inReplyTo":"CAPig+cQ2nTt60iw0Td_MTP7xftt2+OQAx63pOZ4XzH0qeOhDsA@mail.gmail.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-20T20:26:20Z","receivedAt":"2015-07-20T20:26:20Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jul 20, 2015 at 3:14 PM, Eric Sunshine wrote:\n> If you really want to give an example of how to use --cc-cmd\n> (--to-cmd) with a plain text file holding email addresses, maybe\n> something like this instead:\n>\n> Create an EXAMPLES section.\n>\n> Make the bare-bones, static address list script the first example:\n>\n> #!/bin/sh\n> echo <<\\EOF\n> person1@example.com\n> person2@example.com\n> EOF\n>\n> Then add an example showing how to take the fixed address list from a\n> plain text file. Have the user create the following script (let's call\n> it \"anticat\") which cat's all of its input arguments except the final\n> one, which is the patch itself:\n>\n> #!/bin/sh\n> while test $# -gt 1\n> do\n> cat $1\n> shift\n> done\n>\n> And, to use: --to-cccmd='anticat myaddresses.txt'\n\nI forgot to add that even this is iffy as an example because it\ndepends upon the current implementation passing the cmd string to a\nshell, which might not always be the case, and might not be reliably\nimplemented that way on some platforms (such as Windows).\n"},{"id":"266518","messageId":"CAPig+cRbRfOyyx7bx4hM9akN_cO5geZo=cy0+JAprBpnm6qQcw@mail.gmail.com","threadId":"39899","inReplyTo":"1E307B9A21744983970834F69116F358@PhilipOakley","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2015-07-20T20:36:22Z","receivedAt":"2015-07-20T20:36:22Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Jul 20, 2015 at 3:36 PM, Philip Oakley wrote:\n> From: \"Eric Sunshine\" \n>>> + echo <<\\EOF\n>>> + person1@example.com\n>>> + person2@example.com\n>>> + EOF\n>>\n>> I don't know if it deserves mention that the script must be executable\n>> (chmod +x) or should we assume that readers are smart enough to\n>> understand this implicitly? (It probably should be mentioned.)\n>\n> It's there, but it's after the wrap-around. Maybe\n> s/(executable)/(must be executable: `chmod +x`)/\n> to be fully pedantic.\n\nI did see the \"(executable)\", but wasn't sure if it meant executable\nin the 'chmod +x' sense or executable as another name for \"program\".\n\n>> This entire above text about \"cat $addressfile\" seems awfully\n>> inappropriate for a manual page, especially the bit about the terrible\n>> \"cat $file #\" hack.\n>\n> Given that this invocation is why this all kicked off ...\n> 'cat list.txt', being the most simple of commands and a first cargo-cult try\n> for many, I definitely think it's worthwhile including somehow.\n>\n> Perhaps one needs to be more direct with the right invocation.\n>\n> \"A simple `--cc-cmd='cat list.txt #'` is a quick-and-dirty way of using an\n> address list, while ignoring the patch content.\"\n\nIt seems utterly sinful to promulgate this sort of hack to a wider\naudience. If reading addresses from a file is likely to be a common\nneed, then perhaps it ought to have direct support in git-send-email\n(via a new command-line option or something).\n\nAlso, this all may be moot once rl/send-email-aliases[1] lands in a\nrelease since users will then be able to say:\n\n --cc=\"$(cat recipients.txt)\"\n\nprovided that the email addresses in recipients.txt are\ncomma-separated and a POSIX-like shell is being used. Perhaps that\ndeserves an example in the documentation?\n\n[1]: b1c8a11 (send-email: allow multiple emails using --cc, --to and\n--bcc, 2015-06-30)\n"},{"id":"266520","messageId":"996C8C8A69844E44890D09811C57DAC8@PhilipOakley","threadId":"39899","inReplyTo":"xmqqoaj6y50b.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-20T21:35:01Z","receivedAt":"2015-07-20T21:35:01Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Philip Oakley writes:\n>\n>> +git-send-email invokes the cc-cmd like this:\n>> +\n>> + $cc-cmd $patchfilename\n>> +\n>> +Thus the patch itself can be processed to locate appropriate email \n>> address\n>> +information if required.\n>\n> That's not even a valid command line (cc-cmd cannot be a shell\n> variable name), so why bother writing it that way? Rather\n\nWe seem to be going round in circles.\n\nCurrently the --cc-cmd isn't well documented.\n\nI was trying to use, essentially, 'cat list.txt' as the command, which \nshould work according to the current doc, which says nothing about \nhow/if the patch file is to be passed to the command.\n\nEric was able to make clear (*) that the code \nhttps://github.com/git/git/blob/master/git-send-email.perl#L1602 does \nessentially execute '$cc-cmd $patchfilename' where $cc-cmd is the value \nof the --cc-cmd option.\n\nThis meant that my plain vanilla 'cat list.txt' command errored out.\n\nThe question are:\nWhat should the \"command\" look like. (can it be a command, or does it \nhave to be a script??)\nHow should the patch/patchfile be passed - what should the documentation \nguarantee?\n\nAt the moment it's the perl code that defines execution of the rather \nflexible '$cc-cmd $patchfilename' command. (i.e. anything could be in \nthe $cc-cmd string)\n\n>\n> The program that is specified by `cc-cmd` is invoked by `git\n> send-email` with the name of the patch file as an argument;\n> the program can read from it and customize its output based on\n> what the patch file contains.\n>\n> or something like that, perhaps.\n>\n>> +\n>> +A simple solution for a basic address list is to create a 'cc-cmd' \n>> file\n>> +(executable) which provides a list of addressees:\n>\n> There is no \"problem\" stated here that requires your \"solution\". In\n> fact, what problem are you solving?\n\nAs noted above, it's so that I can state a direct command as \nthe --cc-cmd, so that a plain text file listing cc addresses is offered \nto send-email, without needing to create a script.\n\n>\n>> + #!/bin/sh\n>> + echo <<\\EOF\n>> + person1@example.com\n>> + person2@example.com\n>> + EOF\n>\n> That is one simple and denegerate use case; if the program does not\n> need any information from the patch file, it surely has an option\n> not to look at it. But it is not an interesting usage.\n>\n> If you want to add a single example to illustrate how cc-cmd (or\n> to-cmd, or anything that goes thru recipients_cmd()), you should\n> have an example that reads the input and then adds a few hardcoded\n> one.\n>\n> #!/bin/sh\n> # always send it to the logger service\n> echo \"patchlog@example.com\"\n> # tell the bug tracker as necessary\n> if fixes=$(sed -ne 's/^Fixes bug#\\([0-9]*\\)/\\1/p' \"$1\")\n> then\n> echo \"bugs+$fixes@example.com\"\n> fi\n>\n> or something silly like that.\n>\n> And this ...\n>\n>> +Simply, using `cat cc-cmd` as the --cc-cmd (with cc-cmd as the text \n>> file\n>> +of email addresses), does not work as expected as the invocation \n>> becomes:\n>> +\n>> + $cat cc-cmd $patchfilename\n>> +\n>\n> ... and the rest of the patch is unnecessary noise to a reader who\n> read that the single argument to the program is the name of the\n> patchfile, I think. You were trying to avoid the same confusion\n> caused by the sketchy documentaiton, and you already \"solved\" that\n\nI'm not so sure that all other readers would 'know' what went wrong if \nthey tried the same as I, without going through the same Q&A, hence the \ndesire to inform.\n\n> problem by telling the reader what the command takes as its input.\n>\n>> + --cc-cmd='cat cc-cmd #'\n>\n> This heavily depends on the current implementation that happens to\n> pass the command line string to a shell.\n\nNot sure what effective alternative is being suggested - if its a shell \nscript, it'll still hit the shell.\n\n>\n--\nPhilip \n"},{"id":"266521","messageId":"xmqqa8uqxxpn.fsf@gitster.dls.corp.google.com","threadId":"39899","inReplyTo":"996C8C8A69844E44890D09811C57DAC8@PhilipOakley","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-20T22:37:08Z","receivedAt":"2015-07-20T22:37:08Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n> We seem to be going round in circles.\n\nI do not think so.\n\n> Currently the --cc-cmd isn't well documented.\n\nYes, I agree.\n\n> I was trying to use, essentially, 'cat list.txt' as the command, which\n> should work according to the current doc, which says nothing about\n> how/if the patch file is to be passed to the command.\n\nI've already agreed in the message you are responding to that the\ncurrent documentation is sketchy and invite mistakes like yours.\nAnd that is why this series exists, isn't it?\n\n> The question are:\n> What should the \"command\" look like. (can it be a command, or does it\n> have to be a script??)\n> How should the patch/patchfile be passed - what should the\n> documentation guarantee?\n\nYes, I think I already answered that, no?\n\n>> The program that is specified by `cc-cmd` is invoked by `git\n>> send-email` with the name of the patch file as an argument;\n>> the program can read from it and customize its output based on\n>> what the patch file contains.\n>>\n>> or something like that, perhaps.\n\nWe do not care if that program is scripted, or written in java and\ncompiled. It will find the patch in argv[1]. It is up to the\nprogram if it uses that input to customize its output, or it just\noutputs a hardcoded list of addresses.\n\nThat is the only guarantee we would want to give.\n"},{"id":"266525","messageId":"xmqq615exwou.fsf@gitster.dls.corp.google.com","threadId":"39899","inReplyTo":"xmqqa8uqxxpn.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-20T22:59:13Z","receivedAt":"2015-07-20T22:59:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> I was trying to use, essentially, 'cat list.txt' as the command,...\n\nOne thing that needs to be made clear is that I do not think we want\nto encourage `cat list.txt #` abuse in the first place. It is an\nunacceptable hack for us to encourage in the longer term. It may\nhappen to work with the current implementation, but it does so\nmerely by depending on the implementation too much.\n\nIf it is so common to want to spray all your patches to exactly the\nsame list of recipients that is unconditionally determined, having\nmultiple sendemail.cc configuration variables, which are cumulative,\nis already one way to do so, and you do not have to type such a long\noption \"--cc-cmd='cat $filename'\" every time.\n\nAnd if you do not want configuration for some reason, and having a\nlist of addresses in a flat file is so common, we could have a new\noption \"--cc-list=$filename\" to support that use case. I however\ndoubt anything that starts with \"First you make a list of addresses\nin a flat file, and then do this\" is a good solution.\n\nI would think that it would probably be the best way to address \"I\noften want to cc these recipients, but not always\" is to keep a list\nof aliases, each entry of which expands to the recipients, and say\n\"--cc=group\" from the command line to have it expanded to the set of\nrecipients.\n"},{"id":"266597","messageId":"11647308F0684851A72DDF51A486D11D@PhilipOakley","threadId":"39899","inReplyTo":"xmqq615exwou.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.org","sentAt":"2015-07-21T22:48:48Z","receivedAt":"2015-07-21T22:48:48Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"From: \"Junio C Hamano\" \n> Junio C Hamano writes:\n>\n>>> I was trying to use, essentially, 'cat list.txt' as the command,...\n>\n> One thing that needs to be made clear is that I do not think we want\n> to encourage `cat list.txt #` abuse in the first place.\n\nOK [1]\n\n> It is an\n> unacceptable hack for us to encourage in the longer term. It may\n> happen to work with the current implementation, but it does so\n> merely by depending on the implementation too much.\n>\n> If it is so common to want to spray all your patches to exactly the\n> same list of recipients that is unconditionally determined, having\n\nIt wasn't 'unconditional spraying' ;-), rather I'd carefully select who \nto send to for each series, previously with multiple cc=\"..\" on the \ncommand line.\n\n> multiple sendemail.cc configuration variables, which are cumulative,\n> is already one way to do so, and you do not have to type such a long\n> option \"--cc-cmd='cat $filename'\" every time.\n>\n> And if you do not want configuration for some reason, and having a\n> list of addresses in a flat file is so common, we could have a new\n> option \"--cc-list=$filename\" to support that use case. I however\n> doubt anything that starts with \"First you make a list of addresses\n> in a flat file, and then do this\" is a good solution.\n\nFor a longer series, a list will still need collating by the OP somehow, \nbut I don't think that alone would justify a new option.\n\n>\n> I would think that it would probably be the best way to address \"I\n> often want to cc these recipients, but not always\" is to keep a list\n> of aliases, each entry of which expands to the recipients, and say\n> \"--cc=group\" from the command line to have it expanded to the set of\n> recipients.\n>\n[1] You mentioned in the previous email the script command argv[] array, \nwhich I hadn't heard of (for a script), having been used the $1, $2, \nmethod.\n\nGiven that new understanding, IIUC the proposal is that the garantee is \nthe \"--cc-cmd\" should be a single command/script name, with the \npatchfilename passed as $1, and that a 'string string' for \ninterpretation would now be deprecated.\n\nI'll see about a shorter doc patch that restricts itself to just the \nbase aspects, if that would be acceptable?\n--\nPhilip\n"},{"id":"266618","messageId":"xmqqfv4grpcl.fsf@gitster.dls.corp.google.com","threadId":"39899","inReplyTo":"11647308F0684851A72DDF51A486D11D@PhilipOakley","subject":"Re: [PATCH 3/3] doc: give examples for send-email cc-cmd operation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2015-07-22T18:58:50Z","receivedAt":"2015-07-22T18:58:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Philip Oakley\" writes:\n\n>> It is an\n>> unacceptable hack for us to encourage in the longer term. It may\n>> happen to work with the current implementation, but it does so\n>> merely by depending on the implementation too much.\n>>\n>> If it is so common to want to spray all your patches to exactly the\n>> same list of recipients that is unconditionally determined, having\n>\n> It wasn't 'unconditional spraying' ;-), rather I'd carefully select\n> who to send to for each series, ...\n\nI meant unconditional in the sense that all messages in the series\nwill get exactly the same cc: list (instead of the cc-cmd inspecting\neach message and deciding whom to include conditionally).\n\n>> I would think that it would probably be the best way to address \"I\n>> often want to cc these recipients, but not always\" is to keep a list\n>> of aliases, each entry of which expands to the recipients, and say\n>> \"--cc=group\" from the command line to have it expanded to the set of\n>> recipients.\n\nI think one of the topics that was reviewed and queued during this\ncycle will help the above (it may not be in 'master' yet hence not\nin 2.5, but there always is the next release), where it made sure\nthat alias expansion happens more consistently than before.\n"}]}