{"thread":{"id":"56579","subject":"[PATCH] send-email: clarify dual-mode behavior","startedAt":"2021-09-24T12:17:38Z","lastAt":"2021-09-24T18:56:10Z","messageCount":3,"participants":["Bagas Sanjaya","Junio C Hamano","Carlo Arenas"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"436945","messageId":"20210924121352.42138-1-bagasdotme@gmail.com","threadId":"56579","inReplyTo":null,"subject":"[PATCH] send-email: clarify dual-mode behavior","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-09-24T12:13:54Z","receivedAt":"2021-09-24T12:17:38Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"git send-email can be operated in two modes: one that sends\nalready-prepared patches and one that generates patches from\nrevision range on-the-fly for sending. Clarify it in the documentation\nand usage help.\n\nSigned-off-by: Bagas Sanjaya \n---\n This patch is based on [PATCH v5 2/3] send-email: programmatically\n generate bash completions [1]. PATCH v5 3/3 can be replaced with\n this patch, or be integrated as stand-alone patch.\n\n Questions:\n\n 1. Do all supported revision range syntaxes from git rev-list also be\n accepted by git send-email? I only test `A..B` and `B ^A` syntaxes\n and assumed that all are supported.\n 2. Does git send-email also accepts options understood by git\n rev-list? I interpreted that git send-email accepts file, directory\n or rev-list ranges but not rev-list options (I interpreted from\n previous synopsis before this patch but it said `rev-list options`).\n\n [1]:\nhttps://lore.kernel.org/git/20210924024606.20542-3-tbperrotta@gmail.com/\n\n Documentation/git-send-email.txt | 14 ++++++++------\n git-send-email.perl | 3 ++-\n 2 files changed, 10 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 3db4eab4ba..b1d239d74c 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -9,17 +9,19 @@ git-send-email - Send a collection of patches as emails\n SYNOPSIS\n --------\n [verse]\n-'git send-email' [] ...\n+'git send-email' [] ...\n+'git send-email' [] \n 'git send-email' --dump-aliases\n \n \n DESCRIPTION\n -----------\n-Takes the patches given on the command line and emails them out.\n-Patches can be specified as files, directories (which will send all\n-files in the directory), or directly as a revision list. In the\n-last case, any format accepted by linkgit:git-format-patch[1] can\n-be passed to git send-email.\n+In the first form, take the patches in the or and\n+email them out. In the second form, generate patches from the specified\n+ and email them out. can be syntaxes\n+that are accepted by linkgit:git-rev-list[1]. Options that are\n+understood by linkgit:git-format-patch[1] can also be specified in\n+ if the second form is used.\n \n The header of the email is configurable via command-line options. If not\n specified on the command line, the user will be prompted with a ReadLine\ndiff --git a/git-send-email.perl b/git-send-email.perl\nindex 0214b55b4f..5d623f2fa8 100755\n--- a/git-send-email.perl\n+++ b/git-send-email.perl\n@@ -39,7 +39,8 @@ package main;\n \n \n my $USAGE = <\n+git send-email [options] ...\n+git send-email [options] \n git send-email --dump-aliases\n \n Composing:\n-- \n2.25.1\n\n"},{"id":"436986","messageId":"xmqq35ptx3l5.fsf@gitster.g","threadId":"56579","inReplyTo":"20210924121352.42138-1-bagasdotme@gmail.com","subject":"Re: [PATCH] send-email: clarify dual-mode behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-09-24T17:53:26Z","receivedAt":"2021-09-24T17:53:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> git send-email can be operated in two modes: one that sends\n> already-prepared patches and one that generates patches from\n> revision range on-the-fly for sending. Clarify it in the documentation\n> and usage help.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n> This patch is based on [PATCH v5 2/3] send-email: programmatically\n> generate bash completions [1]. PATCH v5 3/3 can be replaced with\n> this patch, or be integrated as stand-alone patch.\n\nHmph. I appreciate your enthusiasm, but I am not sure about this\nchange.\n\n>\n> Questions:\n>\n> 1. Do all supported revision range syntaxes from git rev-list also be\n> accepted by git send-email? I only test `A..B` and `B ^A` syntaxes\n> and assumed that all are supported.\n\nWe do not have to ask that question if we said \"format-patch\noptions\" instead of \"\"revision range\".\n\n> 2. Does git send-email also accepts options understood by git\n> rev-list?\n\nThis becomes an irrelevant question if we used \"format-patch\noptions\" instead of \"revision range\". Does git format-patch accept\noptions understood by git rev-list? Very likely, given that it\nshares the underlying option parser. Do all options understood by\ngit rev-list make sense in that context? Absolutely not. What does\n\"git format-patch --left-right --boundary\" even mean, for example?\n\nBut \"git format-patch -U5 master\" would make sense (show the commits\nnot yet in 'master' in patch form, but using 5-line context instead\nof the usual 3). So it is not \"revision range\", but more like \"what\nformat-patch takes\".\n\nSo from that point of view ...\n\n> +'git send-email' [] ...\n> +'git send-email' [] \n\n... this is not improving Thiago's [3/3], I suspect.\n\nThanks.\n"},{"id":"437017","messageId":"CAPUEspj0y04wwG3cjA-AGXc5AAibYGkEUq-wr0B66+hLrf7_6w@mail.gmail.com","threadId":"56579","inReplyTo":"xmqq35ptx3l5.fsf@gitster.g","subject":"Re: [PATCH] send-email: clarify dual-mode behavior","fromName":"Carlo Arenas","fromEmail":"carenas@gmail.com","sentAt":"2021-09-24T18:55:51Z","receivedAt":"2021-09-24T18:56:10Z","isPatch":true,"sender":{"key":"carenas@gmail.com","avatar":"https://avatars.githubusercontent.com/u/76036?v=4"},"body":"On Fri, Sep 24, 2021 at 10:53 AM Junio C Hamano wrote:\n>\n> > +'git send-email' [] ...\n> > +'git send-email' [] \n>\n> ... this is not improving Thiago's [3/3], I suspect.\n\nI think it does; after all, the original (which I know you proposed)\ndid confuse Bagas who thought it might be missing the tagging of being\noptional.\n\nThe other reasons why this might be better are :\n* because of the points and examples you provided, a vague []\nis better than something that might imply all options taken from\nformat-patch make sense here, which IMHO might be difficult to\nunderstand as logical to you as an experienced user.\n* avoids \"promoting\" this mode, which is known to be problematic as it\ncould lead to patch bombs without the proper review. it might even be\nworth adding mentions to --compose or --annotate to avoid that.\n\nCarlo\n"}]}