[PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders

[PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders

[Aditya Garg]

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 <gargaditya08@live.com>
---
 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

[PATCH v2] docs: explain how to use `git imap-send --list` command to get a list of available folders

[Aditya Garg]

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 <gargaditya08@live.com>
---
 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

Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders

[Junio C Hamano]

Aditya Garg <gargaditya08@live.com> 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:

Re: [PATCH] docs: explain how to use `git imap-send --list` command to get a list of available folders

[Aditya Garg]

> On 22 Jul 2025, at 9:17 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Aditya Garg <gargaditya08@live.com> 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.