[PATCH] gitprotocol-http: document invalid 'want' error handling

QueenJcloud· Nov 1, 2025, 16:15 UTC · lore

Add documentation to describe how the server responds when a client sends an invalid 'want' line during the HTTP protocol exchange. This helps clarify the behavior of Git when handling malformed or unknown object requests, and ensures developers understand how such errors are reported.

Signed-off-by: Queen Ediri Jessa <qjessa662@gmail.com>
---
 Documentation/gitprotocol-http.adoc | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

Show changes to Documentation/gitprotocol-http.adoc +11 −1

diff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc
index d024010414..8818e9dc03 100644
--- a/Documentation/gitprotocol-http.adoc
+++ b/Documentation/gitprotocol-http.adoc
@@ -443,7 +443,17 @@ If no "want" objects are received, send an error:
 TODO: Define error if no "want" lines are requested.
 
 If any "want" object is not reachable, send an error:
-TODO: Define error if an invalid "want" is requested.
+When the client sends an invalid `want` line, the server responds with an
+appropriate error message indicating the invalid object request. This ensures
+the client can detect and handle protocol violations gracefully.
+
+For example, a malformed or unknown object hash in a `want` command will result
+in a response similar to:
+
+    error invalid 'want' <object-id>
+
+This helps maintain clear communication between client and server during
+fetch operations.
 
 Create an empty list, `s_common`.

-- 
2.51.0.573.gb660e2dcb9

Junio C Hamano· Nov 1, 2025, 23:17 UTC · re: QueenJcloud · lore

Re: [PATCH] gitprotocol-http: document invalid 'want' error handling

QueenJcloud <qjessa662@gmail.com> writes:

In the header part of this e-mail, we see this name/address

> From: QueenJcloud <qjessa662@gmail.com>

which I know from the past exchange is different from what you want to be known as to this community (you have your preferred identity on the Signed-off-by: line we see below). In such a case, you can do one of two things.

 * Fix your mail client program so that it places your preferred
   identity on the "From:" header; or

 * Start the body of your message with an extra "in-body header",
   i.e. "From: Queen Ediri Jessa <qjessa662@gmail.com>", and a blank
   line to separate the in-body header from the body of the message.

The former may be preferable, as you'd need to do so only once.

> Add documentation to describe how the server responds when a client sends an
> invalid 'want' line during the HTTP protocol exchange. This helps clarify the
> behavior of Git when handling malformed or unknown object requests, and
> ensures developers understand how such errors are reported.

Is it describing what happens to be the behaviour of one implementation (namely, ours), or do all server implementations give identical error message? Back when the TODO: comment was written and back when there weren't other reimplementations of Git, by definition the error message our implementation give would have been the only official one. But now, it is way too late to declare "here is what our implementation gives out, so everybody else must do the same or they are in error". We'd need to clarify what the intention of this update is in this part of the proposed log message, something like "HTTP server implementation of git-core and jGit give different messages but since their messages share this and that characteristics, which is something any reasonable reimplementations of Git would sharee, specify that as the requirement here" (I am not claiming that it was what you did to come up with this patch and what you want the text of the patch to be taken as; I am just giving a rough illustration of the level of detail expected in the proposed log message to explain what backs the new text in the documentation and how seriously the server implementors need to take it).

Show 12 quoted lines

>  If any "want" object is not reachable, send an error:
> +When the client sends an invalid `want` line, the server responds with an
> +appropriate error message indicating the invalid object request. This ensures
> +the client can detect and handle protocol violations gracefully.
> +
> +For example, a malformed or unknown object hash in a `want` command will result
> +in a response similar to:
> +
> +    error invalid 'want' <object-id>
> +
> +This helps maintain clear communication between client and server during
> +fetch operations.

I am not sure if the additional information given here is worth this many number of lines. Wouldn't something like this

	If any "want" object is not reachable, send an error message
	that includes the offending object name to help the client
	diagnose which "want" command was the bad one.

tell the same thing more concisely and clearly?

Thanks.

patchgitprotocol-http: document invalid 'want' error handling