threads / patch / 63671

patchimap-send: improve error messages for missing configuration

Subject: [PATCH] imap-send: improve error messages for missing configuration

## tl;dr

11 messages between Jun 19, 2025 and Jun 20, 2025. Diffs are folded; open one to read it.

replies: 10people: 3as markdown or json

Jörg Thalheim· Jun 19, 2025, 08:53 UTC · lore

The error message 'no imap store specified' was confusing because it referred to 'store' when the actual missing configuration was 'imap.folder'. Similarly, the host error message provided no guidance on how to fix the issue.

Improve both error messages to:
- Clearly state what configuration is missing
- Provide hints showing the exact git config commands needed
- Include examples of typical values

This helps users quickly understand and resolve configuration issues when using git imap-send.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
---
 imap-send.c | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

Show changes to imap-send.c +6 −2

diff --git a/imap-send.c b/imap-send.c
index 2e812f5a6e..a2d6f6d3f6 100644
--- a/imap-send.c
+++ b/imap-send.c
@@ -1539,13 +1539,17 @@ int cmd_main(int argc, const char **argv)
 		server.port = server.use_ssl ? 993 : 143;
 
 	if (!server.folder) {
-		fprintf(stderr, "no imap store specified\n");
+		fprintf(stderr, "error: no imap folder specified\n");
+		fprintf(stderr, "hint: set the target folder with 'git config imap.folder <folder>'\n");
+		fprintf(stderr, "      (e.g., 'git config imap.folder Drafts')\n");
 		ret = 1;
 		goto out;
 	}
 	if (!server.host) {
 		if (!server.tunnel) {
-			fprintf(stderr, "no imap host specified\n");
+			fprintf(stderr, "error: no imap host specified\n");
+			fprintf(stderr, "hint: set the imap host with 'git config imap.host <host>'\n");
+			fprintf(stderr, "      (e.g., 'git config imap.host imaps://imap.example.com')\n");
 			ret = 1;
 			goto out;
 		}

-- 
2.49.0

Junio C Hamano· Jun 20, 2025, 00:58 UTC · re: Jörg Thalheim · lore

Re: [PATCH] imap-send: improve error messages for missing configuration

"Jörg Thalheim" <joerg@thalheim.io> writes:

Show 17 quoted lines

> The error message 'no imap store specified' was confusing because
> it referred to 'store' when the actual missing configuration was
> 'imap.folder'. Similarly, the host error message provided no
> guidance on how to fix the issue.
>
> Improve both error messages to:
> - Clearly state what configuration is missing
> - Provide hints showing the exact git config commands needed
> - Include examples of typical values
>
> This helps users quickly understand and resolve configuration issues
> when using git imap-send.
>
> Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
> ---
>  imap-send.c | 8 ++++++--
>  1 file changed, 6 insertions(+), 2 deletions(-)

It is curious that you are sending usability improvement patches to imap-send, which I was recently told to be completely broken wrt the use of imap.folder. Is the claim I heard that it is totally broken not true after all, I wonder?

In any case, there are some patches in flight that rewrites the parts of the program this patch wants to update (which addresses that "completely broken" part and makes the program usable again).

Can you fix the messages on top of that work?  By doing

 $ git checkout --detach origin/master
 $ git merge --no-ff -m 'Merge ag/imap-send-resurrection' adbc0b5d
 $ git checkout -b jt/imap-send-error-message-fix

you can prepare the ground and then fix the messages there.

You might want to consider using the advise() API to add the hints, and please make that a separate patch on top of the "What's imap store? We call it a folder!" patch.

Thanks.

Show 24 quoted lines

> diff --git a/imap-send.c b/imap-send.c
> index 2e812f5a6e..a2d6f6d3f6 100644
> --- a/imap-send.c
> +++ b/imap-send.c
> @@ -1539,13 +1539,17 @@ int cmd_main(int argc, const char **argv)
>  		server.port = server.use_ssl ? 993 : 143;
>  
>  	if (!server.folder) {
> -		fprintf(stderr, "no imap store specified\n");
> +		fprintf(stderr, "error: no imap folder specified\n");
> +		fprintf(stderr, "hint: set the target folder with 'git config imap.folder <folder>'\n");
> +		fprintf(stderr, "      (e.g., 'git config imap.folder Drafts')\n");
>  		ret = 1;
>  		goto out;
>  	}
>  	if (!server.host) {
>  		if (!server.tunnel) {
> -			fprintf(stderr, "no imap host specified\n");
> +			fprintf(stderr, "error: no imap host specified\n");
> +			fprintf(stderr, "hint: set the imap host with 'git config imap.host <host>'\n");
> +			fprintf(stderr, "      (e.g., 'git config imap.host imaps://imap.example.com')\n");
>  			ret = 1;
>  			goto out;
>  		}

Aditya Garg· Jun 20, 2025, 05:03 UTC · re: Junio C Hamano · lore

Re: [PATCH] imap-send: improve error messages for missing configuration

On 20 June 2025 6:28:32 am IST, Junio C Hamano <gitster@pobox.com> wrote:

Show 24 quoted lines

>"Jörg Thalheim" <joerg@thalheim.io> writes:
>
>> The error message 'no imap store specified' was confusing because
>> it referred to 'store' when the actual missing configuration was
>> 'imap.folder'. Similarly, the host error message provided no
>> guidance on how to fix the issue.
>>
>> Improve both error messages to:
>> - Clearly state what configuration is missing
>> - Provide hints showing the exact git config commands needed
>> - Include examples of typical values
>>
>> This helps users quickly understand and resolve configuration issues
>> when using git imap-send.
>>
>> Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
>> ---
>>  imap-send.c | 8 ++++++--
>>  1 file changed, 6 insertions(+), 2 deletions(-)
>
>It is curious that you are sending usability improvement patches to
>imap-send, which I was recently told to be completely broken wrt the
>use of imap.folder.  Is the claim I heard that it is totally broken
>not true after all, I wonder?

I assume either the person has used the seen branch, or has not tested the program itself.

Aditya Garg· Jun 20, 2025, 05:05 UTC · re: Aditya Garg · lore

Re: [PATCH] imap-send: improve error messages for missing configuration

On 20 June 2025 10:33:21 am IST, Aditya Garg <gargaditya08@live.com> wrote:

Show 29 quoted lines

>
>
>On 20 June 2025 6:28:32 am IST, Junio C Hamano <gitster@pobox.com> wrote:
>>"Jörg Thalheim" <joerg@thalheim.io> writes:
>>
>>> The error message 'no imap store specified' was confusing because
>>> it referred to 'store' when the actual missing configuration was
>>> 'imap.folder'. Similarly, the host error message provided no
>>> guidance on how to fix the issue.
>>>
>>> Improve both error messages to:
>>> - Clearly state what configuration is missing
>>> - Provide hints showing the exact git config commands needed
>>> - Include examples of typical values
>>>
>>> This helps users quickly understand and resolve configuration issues
>>> when using git imap-send.
>>>
>>> Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
>>> ---
>>>  imap-send.c | 8 ++++++--
>>>  1 file changed, 6 insertions(+), 2 deletions(-)
>>
>>It is curious that you are sending usability improvement patches to
>>imap-send, which I was recently told to be completely broken wrt the
>>use of imap.folder.  Is the claim I heard that it is totally broken
>>not true after all, I wonder?
>
>I assume either the person has used the seen branch, or has not tested the program itself.

Actually you get the error:

no imap store specified

In the broken imap send irrespective of what you do IIRC. Maybe that's what is being addressed here.

Joerg Thalheim· Jun 20, 2025, 06:38 UTC · re: Jörg Thalheim · lore

[PATCH v2 0/2] imap-send: improve error messages for missing configuration

From: Jörg Thalheim <joerg@thalheim.io>

This patch series improves error messages when required IMAP configuration is missing, making it easier for users to understand and fix the issue.

Changes since v1:
- Rebased on top of ag/imap-send-resurrection branch as requested
- Split into two patches:
  * First patch fixes the confusing "store" → "folder" terminology
  * Second patch adds configuration hints using advise() API
- Use error() and advise() instead of fprintf() for better integration
  with Git's message handling

Thanks to Junio for the helpful feedback on v1.

Jörg Thalheim (2):
  imap-send: fix confusing 'store' terminology in error message
  imap-send: improve error messages with configuration hints

 imap-send.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

-- 
2.49.0

Joerg Thalheim· Jun 20, 2025, 06:38 UTC · re: Joerg Thalheim · lore

[PATCH v2 1/2] imap-send: fix confusing 'store' terminology in error message

From: Jörg Thalheim <joerg@thalheim.io>

The error message 'no imap store specified' is misleading because it refers to 'store' when the actual missing configuration is 'imap.folder'. Update the message to use the correct terminology that matches the configuration variable name.

This reduces confusion for users who might otherwise look for non-existent 'imap.store' configuration when they see this error.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
---
 imap-send.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Show changes to imap-send.c +1 −1

diff --git a/imap-send.c b/imap-send.c
index ed4c34dadd..33690cd66a 100644
--- a/imap-send.c
+++ b/imap-send.c
@@ -1831,7 +1831,7 @@ int cmd_main(int argc, const char **argv)
 	}
 
 	if (!server.folder) {
-		fprintf(stderr, "no IMAP store specified\n");
+		fprintf(stderr, "no IMAP folder specified\n");
 		ret = 1;
 		goto out;
 	}

-- 
2.49.0

Joerg Thalheim· Jun 20, 2025, 06:38 UTC · re: Joerg Thalheim · lore

[PATCH v2 2/2] imap-send: improve error messages with configuration hints

From: Jörg Thalheim <joerg@thalheim.io>

Replace basic error messages with more helpful ones that guide users on how to resolve configuration issues. When imap.host or imap.folder are missing, provide the exact git config commands needed to fix the problem, along with examples of typical values.

This uses the advise() API to display hints that can be disabled by users who don't want them, and error() for the main error message.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
---
 imap-send.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

Show changes to imap-send.c +7 −2

diff --git a/imap-send.c b/imap-send.c
index 33690cd66a..e4613aa236 100644
--- a/imap-send.c
+++ b/imap-send.c
@@ -25,6 +25,7 @@
 #define DISABLE_SIGN_COMPARE_WARNINGS
 
 #include "git-compat-util.h"
+#include "advice.h"
 #include "config.h"
 #include "credential.h"
 #include "gettext.h"
@@ -1811,7 +1812,9 @@ int cmd_main(int argc, const char **argv)
 
 	if (!server.host) {
 		if (!server.tunnel) {
-			fprintf(stderr, "no IMAP host specified\n");
+			error(_("no IMAP host specified"));
+			advise(_("set the IMAP host with 'git config imap.host <host>'"));
+			advise(_("(e.g., 'git config imap.host imaps://imap.example.com')"));
 			ret = 1;
 			goto out;
 		}
@@ -1831,7 +1834,9 @@ int cmd_main(int argc, const char **argv)
 	}
 
 	if (!server.folder) {
-		fprintf(stderr, "no IMAP folder specified\n");
+		error(_("no IMAP folder specified"));
+		advise(_("set the target folder with 'git config imap.folder <folder>'"));
+		advise(_("(e.g., 'git config imap.folder Drafts')"));
 		ret = 1;
 		goto out;
 	}

-- 
2.49.0

Junio C Hamano· Jun 20, 2025, 15:44 UTC · re: Joerg Thalheim · lore

Re: [PATCH v2 2/2] imap-send: improve error messages with configuration hints

Joerg Thalheim <joerg@thalheim.io> writes:

Show 9 quoted lines

> From: Jörg Thalheim <joerg@thalheim.io>
>
> Replace basic error messages with more helpful ones that guide users
> on how to resolve configuration issues. When imap.host or imap.folder
> are missing, provide the exact git config commands needed to fix the
> problem, along with examples of typical values.
>
> This uses the advise() API to display hints that can be disabled
> by users who don't want them,

Not quite. We do not encourage or condone wholesale disabling of all advise messages by end users. The advice_if_enabled() helper allows selective disabling of individual messages that the user has seen often enough and find no more need for help, but I do not think it is advisable (no pun intended) to use it in these particular code paths, simply because once the relevant configuration variables are set, the users will not see the errors anymore.

The reason advise() was suggested was primarily because of its better handling of multi-line messages. It can be fed a multi-line message (i.e., with embedded LF in it), and give "hint:" prefix to each line, which is lacking from the error(), warning(), die() family of messaging functions.

> +			error(_("no IMAP host specified"));
> +			advise(_("set the IMAP host with 'git config imap.host <host>'"));
> +			advise(_("(e.g., 'git config imap.host imaps://imap.example.com')"));

Give a single multi-line message to a single advise() call, i.e.,

	advice(_("set the IMAP host with ... <host>'.\n"
        	 "(e.g., 'git config ....com')"));

instead of two back-to-back calls to advise. It allows the translators to find points to break lines better than the programmer who wrote these advise() call(s).

Show 8 quoted lines

> @@ -1831,7 +1834,9 @@ int cmd_main(int argc, const char **argv)
>  	}
>  
>  	if (!server.folder) {
> -		fprintf(stderr, "no IMAP folder specified\n");
> +		error(_("no IMAP folder specified"));
> +		advise(_("set the target folder with 'git config imap.folder <folder>'"));
> +		advise(_("(e.g., 'git config imap.folder Drafts')"));

Ditto.

As a #leftoverbit we might want to inspect many fprintf(stderr) still remain in this program after this patch and turn them into calls to appropriate error() or warning() or whatever, but that certainly would be outside the scope of this patch.

Thanks.

Joerg Thalheim· Jun 20, 2025, 15:56 UTC · re: Jörg Thalheim · lore

[PATCH v3 0/2] imap-send: improve error messages for missing configuration

From: Jörg Thalheim <joerg@thalheim.io>

This patch series improves error messages when required IMAP configuration is missing, making it easier for users to understand and fix the issue.

Changes since v2:
- Use single advise() calls with multi-line strings instead of multiple
  calls, as suggested by Junio
- Simplified commit message explanation about advise() API

Changes since v1:
- Rebased on top of ag/imap-send-resurrection branch
- Split into two patches:
  * First patch fixes the confusing "store" → "folder" terminology
  * Second patch adds configuration hints using advise() API
- Use error() and advise() instead of fprintf()

Thanks to Junio for the helpful reviews.

Jörg Thalheim (2):
  imap-send: fix confusing 'store' terminology in error message
  imap-send: improve error messages with configuration hints

 imap-send.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

-- 
2.49.0

Joerg Thalheim· Jun 20, 2025, 15:56 UTC · re: Joerg Thalheim · lore

[PATCH v3 1/2] imap-send: fix confusing 'store' terminology in error message

From: Jörg Thalheim <joerg@thalheim.io>

This reduces confusion for users who might otherwise look for non-existent 'imap.store' configuration when they see this error.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
---
 imap-send.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Show changes to imap-send.c +1 −1

diff --git a/imap-send.c b/imap-send.c
index ed4c34dadd..33690cd66a 100644
--- a/imap-send.c
+++ b/imap-send.c
@@ -1831,7 +1831,7 @@ int cmd_main(int argc, const char **argv)
 	}
 
 	if (!server.folder) {
-		fprintf(stderr, "no IMAP store specified\n");
+		fprintf(stderr, "no IMAP folder specified\n");
 		ret = 1;
 		goto out;
 	}

-- 
2.49.0

Joerg Thalheim· Jun 20, 2025, 15:56 UTC · re: Joerg Thalheim · lore

[PATCH v3 2/2] imap-send: improve error messages with configuration hints

From: Jörg Thalheim <joerg@thalheim.io>

Use the advise() API to display hints in a multi-line format with proper "hint:" prefixes for each line.

Signed-off-by: Jörg Thalheim <joerg@thalheim.io>
---
 imap-send.c | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

Show changes to imap-send.c +7 −2

diff --git a/imap-send.c b/imap-send.c
index 33690cd66a..b6fa90960f 100644
--- a/imap-send.c
+++ b/imap-send.c
@@ -25,6 +25,7 @@
 #define DISABLE_SIGN_COMPARE_WARNINGS
 
 #include "git-compat-util.h"
+#include "advice.h"
 #include "config.h"
 #include "credential.h"
 #include "gettext.h"
@@ -1811,7 +1812,9 @@ int cmd_main(int argc, const char **argv)
 
 	if (!server.host) {
 		if (!server.tunnel) {
-			fprintf(stderr, "no IMAP host specified\n");
+			error(_("no IMAP host specified"));
+			advise(_("set the IMAP host with 'git config imap.host <host>'.\n"
+				 "(e.g., 'git config imap.host imaps://imap.example.com')"));
 			ret = 1;
 			goto out;
 		}
@@ -1831,7 +1834,9 @@ int cmd_main(int argc, const char **argv)
 	}
 
 	if (!server.folder) {
-		fprintf(stderr, "no IMAP folder specified\n");
+		error(_("no IMAP folder specified"));
+		advise(_("set the target folder with 'git config imap.folder <folder>'.\n"
+			 "(e.g., 'git config imap.folder Drafts')"));
 		ret = 1;
 		goto out;
 	}

-- 
2.49.0