{"thread":{"id":"63820","subject":"[PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders","startedAt":"2025-07-22T11:43:31Z","lastAt":"2025-07-22T16:35:09Z","messageCount":4,"participants":["Aditya Garg","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"522434","messageId":"20250722114246.20422-1-gargaditya08@live.com","threadId":"63820","inReplyTo":null,"subject":"[PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders","fromName":"Aditya Garg","fromEmail":"gargaditya08@live.com","sentAt":"2025-07-22T11:43:27Z","receivedAt":"2025-07-22T11:43:31Z","isPatch":true,"sender":{"key":"gargaditya08@live.com","avatar":"https://avatars.githubusercontent.com/u/85610623?v=4"},"body":"The output `git imap-send --list` command can be a bit confusing for new\nusers since the IMAP LIST command output is very verbose. Help such users\nto analyse the same by using an example output.\n\nSigned-off-by: Aditya Garg \n---\n Documentation/git-imap-send.adoc | 28 ++++++++++++++++++++++++++++\n 1 file changed, 28 insertions(+)\n\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 17147f93c3..6411fee046 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -68,6 +68,34 @@ include::includes/cmd-config-section-rest.adoc[]\n \n include::config/imap.adoc[]\n \n+GETTING A LIST OF AVAILABLE FOLDERS\n+-----------------------------------\n+\n+In order to send an email to a specific folder, you need to know the correct name of\n+intended folder in your mailbox. The names like \"Junk\", \"Trash\" etc. displayed by\n+various email clients need to be the actual names of the folders stored in the mail\n+server of your email provider.\n+\n+In order to get the correct folder name to be used with `git imap-send`, you can run\n+`git imap-send --list`. This will display a list of valid folder names. An example\n+of such an output when run on a Gmail account is:\n+\n+.........................\n+* LIST (\\HasNoChildren) \"/\" \"INBOX\"\n+* LIST (\\HasChildren \\Noselect) \"/\" \"[Gmail]\"\n+* LIST (\\All \\HasNoChildren) \"/\" \"[Gmail]/All Mail\"\n+* LIST (\\Drafts \\HasNoChildren) \"/\" \"[Gmail]/Drafts\"\n+* LIST (\\HasNoChildren \\Important) \"/\" \"[Gmail]/Important\"\n+* LIST (\\HasNoChildren \\Sent) \"/\" \"[Gmail]/Sent Mail\"\n+* LIST (\\HasNoChildren \\Junk) \"/\" \"[Gmail]/Spam\"\n+* LIST (\\Flagged \\HasNoChildren) \"/\" \"[Gmail]/Starred\"\n+* LIST (\\HasNoChildren \\Trash) \"/\" \"[Gmail]/Trash\"\n+.........................\n+\n+Here, you can observe that the correct name for the \"Junk\" folder is `[Gmail]/Spam`\n+and for the \"Trash\" folder is `[Gmail]/Trash`. Similar logic can be used to determine\n+other folders as well.\n+\n EXAMPLES\n --------\n Using tunnel mode:\n-- \n2.50.1.319.gda7cee769f\n\n"},{"id":"522435","messageId":"20250722114827.22493-1-gargaditya08@live.com","threadId":"63820","inReplyTo":"20250722114246.20422-1-gargaditya08@live.com","subject":"[PATCH v2] docs: explain how to use `git imap-send --list` command to get a list of available folders","fromName":"Aditya Garg","fromEmail":"gargaditya08@live.com","sentAt":"2025-07-22T11:48:42Z","receivedAt":"2025-07-22T11:48:48Z","isPatch":true,"sender":{"key":"gargaditya08@live.com","avatar":"https://avatars.githubusercontent.com/u/85610623?v=4"},"body":"The output `git imap-send --list` command can be a bit confusing for new\nusers since the IMAP LIST command output is very verbose. Help such users\nto analyse the same by using an example output.\n\nSigned-off-by: Aditya Garg \n---\n Documentation/git-imap-send.adoc | 28 ++++++++++++++++++++++++++++\n 1 file changed, 28 insertions(+)\n\ndiff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc\nindex 17147f93c3..278e5ccd36 100644\n--- a/Documentation/git-imap-send.adoc\n+++ b/Documentation/git-imap-send.adoc\n@@ -68,6 +68,34 @@ include::includes/cmd-config-section-rest.adoc[]\n \n include::config/imap.adoc[]\n \n+GETTING A LIST OF AVAILABLE FOLDERS\n+-----------------------------------\n+\n+In order to send an email to a specific folder, you need to know the correct name of\n+intended folder in your mailbox. The names like \"Junk\", \"Trash\" etc. displayed by\n+various email clients need not be the actual names of the folders stored in the mail\n+server of your email provider.\n+\n+In order to get the correct folder name to be used with `git imap-send`, you can run\n+`git imap-send --list`. This will display a list of valid folder names. An example\n+of such an output when run on a Gmail account is:\n+\n+.........................\n+* LIST (\\HasNoChildren) \"/\" \"INBOX\"\n+* LIST (\\HasChildren \\Noselect) \"/\" \"[Gmail]\"\n+* LIST (\\All \\HasNoChildren) \"/\" \"[Gmail]/All Mail\"\n+* LIST (\\Drafts \\HasNoChildren) \"/\" \"[Gmail]/Drafts\"\n+* LIST (\\HasNoChildren \\Important) \"/\" \"[Gmail]/Important\"\n+* LIST (\\HasNoChildren \\Sent) \"/\" \"[Gmail]/Sent Mail\"\n+* LIST (\\HasNoChildren \\Junk) \"/\" \"[Gmail]/Spam\"\n+* LIST (\\Flagged \\HasNoChildren) \"/\" \"[Gmail]/Starred\"\n+* LIST (\\HasNoChildren \\Trash) \"/\" \"[Gmail]/Trash\"\n+.........................\n+\n+Here, you can observe that the correct name for the \"Junk\" folder is `[Gmail]/Spam`\n+and for the \"Trash\" folder is `[Gmail]/Trash`. Similar logic can be used to determine\n+other folders as well.\n+\n EXAMPLES\n --------\n Using tunnel mode:\n\nRange-diff against v1:\n1: 369d96569e ! 1: 75cafeebf1 docs: explain how to use `git imap-send --list` command to get a list of available folders\n @@ Documentation/git-imap-send.adoc: include::includes/cmd-config-section-rest.adoc\n +\n +In order to send an email to a specific folder, you need to know the correct name of\n +intended folder in your mailbox. The names like \"Junk\", \"Trash\" etc. displayed by\n -+various email clients need to be the actual names of the folders stored in the mail\n ++various email clients need not be the actual names of the folders stored in the mail\n +server of your email provider.\n +\n +In order to get the correct folder name to be used with `git imap-send`, you can run\n-- \n2.50.1.319.gda7cee769f\n\n"},{"id":"522458","messageId":"xmqqfreotegx.fsf@gitster.g","threadId":"63820","inReplyTo":"20250722114246.20422-1-gargaditya08@live.com","subject":"Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-07-22T15:47:10Z","receivedAt":"2025-07-22T15:47:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Aditya Garg writes:\n\n> The output `git imap-send --list` command can be a bit confusing for new\n> users since the IMAP LIST command output is very verbose. Help such users\n> to analyse the same by using an example output.\n\nThe documentation added by 067a91b0 (imap-send: add ability to list\nthe available folders, 2025-06-20) is overly insufficient, so let's\nqueue this update on top of it.\n\nBut I am not sure if \"very verbose\" is a cause for worry. I would\nagree if the argument were that it is not very friendly to end-users\nto throw raw IMAP protocol messages at them. But it is what needs\nto be fixed in the implementation, not papered over with\ndocumentation.\n\nThanks.\n\n> +GETTING A LIST OF AVAILABLE FOLDERS\n> +-----------------------------------\n> +\n> +In order to send an email to a specific folder, you need to know the correct name of\n> +intended folder in your mailbox. The names like \"Junk\", \"Trash\" etc. displayed by\n> +various email clients need to be the actual names of the folders stored in the mail\n> +server of your email provider.\n> +\n> +In order to get the correct folder name to be used with `git imap-send`, you can run\n> +`git imap-send --list`. This will display a list of valid folder names. An example\n> +of such an output when run on a Gmail account is:\n> +\n> +.........................\n> +* LIST (\\HasNoChildren) \"/\" \"INBOX\"\n> +* LIST (\\HasChildren \\Noselect) \"/\" \"[Gmail]\"\n> +* LIST (\\All \\HasNoChildren) \"/\" \"[Gmail]/All Mail\"\n> +* LIST (\\Drafts \\HasNoChildren) \"/\" \"[Gmail]/Drafts\"\n> +* LIST (\\HasNoChildren \\Important) \"/\" \"[Gmail]/Important\"\n> +* LIST (\\HasNoChildren \\Sent) \"/\" \"[Gmail]/Sent Mail\"\n> +* LIST (\\HasNoChildren \\Junk) \"/\" \"[Gmail]/Spam\"\n> +* LIST (\\Flagged \\HasNoChildren) \"/\" \"[Gmail]/Starred\"\n> +* LIST (\\HasNoChildren \\Trash) \"/\" \"[Gmail]/Trash\"\n> +.........................\n> +\n> +Here, you can observe that the correct name for the \"Junk\" folder is `[Gmail]/Spam`\n> +and for the \"Trash\" folder is `[Gmail]/Trash`. Similar logic can be used to determine\n> +other folders as well.\n> +\n> EXAMPLES\n> --------\n> Using tunnel mode:\n"},{"id":"522469","messageId":"06DB740D-4A94-4588-8666-DEF29C46538C@live.com","threadId":"63820","inReplyTo":"xmqqfreotegx.fsf@gitster.g","subject":"Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders","fromName":"Aditya Garg","fromEmail":"gargaditya08@live.com","sentAt":"2025-07-22T16:35:05Z","receivedAt":"2025-07-22T16:35:09Z","isPatch":true,"sender":{"key":"gargaditya08@live.com","avatar":"https://avatars.githubusercontent.com/u/85610623?v=4"},"body":"\n\n> On 22 Jul 2025, at 9:17 PM, Junio C Hamano wrote:\n> \n> Aditya Garg writes:\n> \n>> The output `git imap-send --list` command can be a bit confusing for new\n>> users since the IMAP LIST command output is very verbose. Help such users\n>> to analyse the same by using an example output.\n> \n> The documentation added by 067a91b0 (imap-send: add ability to list\n> the available folders, 2025-06-20) is overly insufficient, so let's\n> queue this update on top of it.\n> \n> But I am not sure if \"very verbose\" is a cause for worry. I would\n> agree if the argument were that it is not very friendly to end-users\n> to throw raw IMAP protocol messages at them. But it is what needs\n> to be fixed in the implementation, not papered over with\n> documentation.\n\nIt’s not really easy to make it more user friendly. Regex with C is a PITA for me, and different email servers might have slightly different ways to express the same output. Also, this much verbosity gives necessary details to locate subfolders, tags etc.\n\n"}]}