# [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders 4 messages from 2025-07-22 to 2025-07-22. Participants: Aditya Garg, Junio C Hamano. Thread: https://gitlist.dev/t/63820 ## Aditya Garg, 2025-07-22 11:43 Subject: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders Message-ID: <20250722114246.20422-1-gargaditya08@live.com> URL: https://gitlist.dev/e/20250722114246.20422-1-gargaditya08%40live.com ``` The output `git imap-send --list` command can be a bit confusing for new users since the IMAP LIST command output is very verbose. Help such users to analyse the same by using an example output. Signed-off-by: Aditya Garg --- Documentation/git-imap-send.adoc | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc index 17147f93c3..6411fee046 100644 --- a/Documentation/git-imap-send.adoc +++ b/Documentation/git-imap-send.adoc @@ -68,6 +68,34 @@ include::includes/cmd-config-section-rest.adoc[] include::config/imap.adoc[] +GETTING A LIST OF AVAILABLE FOLDERS +----------------------------------- + +In order to send an email to a specific folder, you need to know the correct name of +intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by +various email clients need to be the actual names of the folders stored in the mail +server of your email provider. + +In order to get the correct folder name to be used with `git imap-send`, you can run +`git imap-send --list`. This will display a list of valid folder names. An example +of such an output when run on a Gmail account is: + +......................... +* LIST (\HasNoChildren) "/" "INBOX" +* LIST (\HasChildren \Noselect) "/" "[Gmail]" +* LIST (\All \HasNoChildren) "/" "[Gmail]/All Mail" +* LIST (\Drafts \HasNoChildren) "/" "[Gmail]/Drafts" +* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important" +* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail" +* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam" +* LIST (\Flagged \HasNoChildren) "/" "[Gmail]/Starred" +* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash" +......................... + +Here, you can observe that the correct name for the "Junk" folder is `[Gmail]/Spam` +and for the "Trash" folder is `[Gmail]/Trash`. Similar logic can be used to determine +other folders as well. + EXAMPLES -------- Using tunnel mode: -- 2.50.1.319.gda7cee769f ``` ## Aditya Garg, 2025-07-22 11:48 Subject: [PATCH v2] docs: explain how to use `git imap-send --list` command to get a list of available folders Message-ID: <20250722114827.22493-1-gargaditya08@live.com> URL: https://gitlist.dev/e/20250722114827.22493-1-gargaditya08%40live.com In-Reply-To: <20250722114246.20422-1-gargaditya08@live.com> ``` The output `git imap-send --list` command can be a bit confusing for new users since the IMAP LIST command output is very verbose. Help such users to analyse the same by using an example output. Signed-off-by: Aditya Garg --- Documentation/git-imap-send.adoc | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/Documentation/git-imap-send.adoc b/Documentation/git-imap-send.adoc index 17147f93c3..278e5ccd36 100644 --- a/Documentation/git-imap-send.adoc +++ b/Documentation/git-imap-send.adoc @@ -68,6 +68,34 @@ include::includes/cmd-config-section-rest.adoc[] include::config/imap.adoc[] +GETTING A LIST OF AVAILABLE FOLDERS +----------------------------------- + +In order to send an email to a specific folder, you need to know the correct name of +intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by +various email clients need not be the actual names of the folders stored in the mail +server of your email provider. + +In order to get the correct folder name to be used with `git imap-send`, you can run +`git imap-send --list`. This will display a list of valid folder names. An example +of such an output when run on a Gmail account is: + +......................... +* LIST (\HasNoChildren) "/" "INBOX" +* LIST (\HasChildren \Noselect) "/" "[Gmail]" +* LIST (\All \HasNoChildren) "/" "[Gmail]/All Mail" +* LIST (\Drafts \HasNoChildren) "/" "[Gmail]/Drafts" +* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important" +* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail" +* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam" +* LIST (\Flagged \HasNoChildren) "/" "[Gmail]/Starred" +* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash" +......................... + +Here, you can observe that the correct name for the "Junk" folder is `[Gmail]/Spam` +and for the "Trash" folder is `[Gmail]/Trash`. Similar logic can be used to determine +other folders as well. + EXAMPLES -------- Using tunnel mode: Range-diff against v1: 1: 369d96569e ! 1: 75cafeebf1 docs: explain how to use `git imap-send --list` command to get a list of available folders @@ Documentation/git-imap-send.adoc: include::includes/cmd-config-section-rest.adoc + +In order to send an email to a specific folder, you need to know the correct name of +intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by -+various email clients need to be the actual names of the folders stored in the mail ++various email clients need not be the actual names of the folders stored in the mail +server of your email provider. + +In order to get the correct folder name to be used with `git imap-send`, you can run -- 2.50.1.319.gda7cee769f ``` ## Junio C Hamano, 2025-07-22 15:47 Subject: Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders Message-ID: URL: https://gitlist.dev/e/xmqqfreotegx.fsf%40gitster.g In-Reply-To: <20250722114246.20422-1-gargaditya08@live.com> ``` Aditya Garg writes: > The output `git imap-send --list` command can be a bit confusing for new > users since the IMAP LIST command output is very verbose. Help such users > to analyse the same by using an example output. The documentation added by 067a91b0 (imap-send: add ability to list the available folders, 2025-06-20) is overly insufficient, so let's queue this update on top of it. But I am not sure if "very verbose" is a cause for worry. I would agree if the argument were that it is not very friendly to end-users to throw raw IMAP protocol messages at them. But it is what needs to be fixed in the implementation, not papered over with documentation. Thanks. > +GETTING A LIST OF AVAILABLE FOLDERS > +----------------------------------- > + > +In order to send an email to a specific folder, you need to know the correct name of > +intended folder in your mailbox. The names like "Junk", "Trash" etc. displayed by > +various email clients need to be the actual names of the folders stored in the mail > +server of your email provider. > + > +In order to get the correct folder name to be used with `git imap-send`, you can run > +`git imap-send --list`. This will display a list of valid folder names. An example > +of such an output when run on a Gmail account is: > + > +......................... > +* LIST (\HasNoChildren) "/" "INBOX" > +* LIST (\HasChildren \Noselect) "/" "[Gmail]" > +* LIST (\All \HasNoChildren) "/" "[Gmail]/All Mail" > +* LIST (\Drafts \HasNoChildren) "/" "[Gmail]/Drafts" > +* LIST (\HasNoChildren \Important) "/" "[Gmail]/Important" > +* LIST (\HasNoChildren \Sent) "/" "[Gmail]/Sent Mail" > +* LIST (\HasNoChildren \Junk) "/" "[Gmail]/Spam" > +* LIST (\Flagged \HasNoChildren) "/" "[Gmail]/Starred" > +* LIST (\HasNoChildren \Trash) "/" "[Gmail]/Trash" > +......................... > + > +Here, you can observe that the correct name for the "Junk" folder is `[Gmail]/Spam` > +and for the "Trash" folder is `[Gmail]/Trash`. Similar logic can be used to determine > +other folders as well. > + > EXAMPLES > -------- > Using tunnel mode: ``` ## Aditya Garg, 2025-07-22 16:35 Subject: Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders Message-ID: <06DB740D-4A94-4588-8666-DEF29C46538C@live.com> URL: https://gitlist.dev/e/06DB740D-4A94-4588-8666-DEF29C46538C%40live.com In-Reply-To: ``` > On 22 Jul 2025, at 9:17 PM, Junio C Hamano wrote: > > Aditya Garg writes: > >> The output `git imap-send --list` command can be a bit confusing for new >> users since the IMAP LIST command output is very verbose. Help such users >> to analyse the same by using an example output. > > The documentation added by 067a91b0 (imap-send: add ability to list > the available folders, 2025-06-20) is overly insufficient, so let's > queue this update on top of it. > > But I am not sure if "very verbose" is a cause for worry. I would > agree if the argument were that it is not very friendly to end-users > to throw raw IMAP protocol messages at them. But it is what needs > to be fixed in the implementation, not papered over with > documentation. It’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. ```