diff mbox series

[v2] doc: update http.cookieFile with in-memory cookie processing

Message ID pull.1733.v2.git.git.1720687008915.gitgitgadget@gmail.com (mailing list archive)
State New
Headers show
Series [v2] doc: update http.cookieFile with in-memory cookie processing | expand

Commit Message

Piotr Szlazak July 11, 2024, 8:36 a.m. UTC 
From: Piotr Szlazak <piotr.szlazak@gmail.com>

Information added how to enable in-memory cookies
processing. Cookies from server will be accepted and send
back in successive requests within same connection.

At the moment documentation only mentions how to read
cookies from the given file and how to save them to the file
using http.saveCookies.

curl / libcurl will process cookies in memory if file name
is blank. Check curl manpage:
https://curl.se/docs/manpage.html#-b
This is described here in more details:
https://everything.curl.dev/http/cookies/engine.html
And also explained here:
https://www.youtube.com/watch?v=V5vZWHP-RqU&t=11459s

Git documentation was updated to include suggestion how to
enable this by setting empty value for http.cookieFile.

Changes since V1:
- better explanation what in-memory processing means
- added explanation that http.saveCookies does not work
  if http.cookieFile was set to empty value

Signed-off-by: Piotr Szlazak <piotr.szlazak@gmail.com>
---
    Update http.cookieFile with in-memory cookie processing

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1733%2Fpszlazak%2Fdocumentation-cookieFile-in-memory-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1733/pszlazak/documentation-cookieFile-in-memory-v2
Pull-Request: https://github.com/git/git/pull/1733

Range-diff vs v1:

 1:  5e9b3924224 ! 1:  c4d41b5884d doc: update http.cookieFile with in-memory cookie processing
     @@ Commit message
          Git documentation was updated to include suggestion how to
          enable this by setting empty value for http.cookieFile.
      
     +    Changes since V1:
     +    - better explanation what in-memory processing means
     +    - added explanation that http.saveCookies does not work
     +      if http.cookieFile was set to empty value
     +
          Signed-off-by: Piotr Szlazak <piotr.szlazak@gmail.com>
      
       ## Documentation/config/http.txt ##
     @@ Documentation/config/http.txt: http.extraHeader::
      -	in the Git http session, if they match the server. The file format
      -	of the file to read cookies from should be plain HTTP headers or
      -	the Netscape/Mozilla cookie file format (see `curl(1)`).
     +-	NOTE that the file specified with http.cookieFile is used only as
     +-	input unless http.saveCookies is set.
      +	which should be used in the Git http session, if they match the server.
      +	The file format of the file to read cookies from should be plain HTTP
      +	headers or the Netscape/Mozilla cookie file format (see `curl(1)`).
     -+	Set it to empty value, to enable in-memory cookies processing.
     - 	NOTE that the file specified with http.cookieFile is used only as
     - 	input unless http.saveCookies is set.
     ++	Set it to empty value (''), to accept only new cookies from the server and
     ++	send them back in successive requests within same connection. NOTE that the
     ++	file specified with http.cookieFile is used only as input unless
     ++	http.saveCookies is set.
     + 
     + http.saveCookies::
     + 	If set, store cookies received during requests to the file specified by
     +-	http.cookieFile. Has no effect if http.cookieFile is unset.
     ++	http.cookieFile. Has no effect if http.cookieFile is not set or set to empty
     ++	value ('').
       
     + http.version::
     + 	Use the specified HTTP protocol version when communicating with a server.


 Documentation/config/http.txt | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)


base-commit: 66ac6e4bcd111be3fa9c2a6b3fafea718d00678d

Comments

Junio C Hamano July 11, 2024, 4:05 p.m. UTC | #1 
"Piotr Szlazak via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Piotr Szlazak <piotr.szlazak@gmail.com>

Thanks.

> Information added how to enable in-memory cookies
> processing. Cookies from server will be accepted and send
> back in successive requests within same connection.
>
> At the moment documentation only mentions how to read
> cookies from the given file and how to save them to the file
> using http.saveCookies.
>
> curl / libcurl will process cookies in memory if file name
> is blank. Check curl manpage:
> https://curl.se/docs/manpage.html#-b
> This is described here in more details:
> https://everything.curl.dev/http/cookies/engine.html
> And also explained here:
> https://www.youtube.com/watch?v=V5vZWHP-RqU&t=11459s
>
> Git documentation was updated to include suggestion how to
> enable this by setting empty value for http.cookieFile.
>
> Changes since V1:
> - better explanation what in-memory processing means
> - added explanation that http.saveCookies does not work
>   if http.cookieFile was set to empty value
>
> Signed-off-by: Piotr Szlazak <piotr.szlazak@gmail.com>
> ---

Here is how I amended the log message, FYI.

    doc: update http.cookieFile with in-memory cookie processing

    Documentation only mentions how to read cookies from the given file
    and how to save them to the file using http.saveCookies.

    But underlying libcURL allows the HTTP cookies used only in memory;
    cookies from the server will be accepted and sent back in successive
    requests within same connection, by using an empty string as the
    filename.  Document this.

    Signed-off-by: Piotr Szlazak <piotr.szlazak@gmail.com>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

A few points to note:

 - It is our convention to start a proposed log message by
   describing the current status in present tense ("currently", "at
   the moment", etc., are not needed).

 - The observation of the current status is followed by the
   description of a problem the patch tries to solve.

 - And then finally we give an order to the codebase to "become like
   so".

 - Changes between iterations do not belong to the log message, as
   the log messages are written for those who run "git log"; to
   them, our previous iterations do not exist.  We describe changes
   below the "---" lines.

> diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
> index 2d4e0c9b869..e71ca11c10b 100644
> --- a/Documentation/config/http.txt
> +++ b/Documentation/config/http.txt
> @@ -78,16 +78,18 @@ http.extraHeader::
>  
>  http.cookieFile::
>  	The pathname of a file containing previously stored cookie lines,
> -	which should be used
> -	in the Git http session, if they match the server. The file format
> -	of the file to read cookies from should be plain HTTP headers or
> -	the Netscape/Mozilla cookie file format (see `curl(1)`).
> -	NOTE that the file specified with http.cookieFile is used only as
> -	input unless http.saveCookies is set.
> +	which should be used in the Git http session, if they match the server.
> +	The file format of the file to read cookies from should be plain HTTP
> +	headers or the Netscape/Mozilla cookie file format (see `curl(1)`).
> +	Set it to empty value (''), to accept only new cookies from the server and
> +	send them back in successive requests within same connection. NOTE that the
> +	file specified with http.cookieFile is used only as input unless
> +	http.saveCookies is set.
>  
>  http.saveCookies::
>  	If set, store cookies received during requests to the file specified by
> -	http.cookieFile. Has no effect if http.cookieFile is unset.
> +	http.cookieFile. Has no effect if http.cookieFile is not set or set to empty
> +	value ('').

I reformatted the patch and added minor word-smithing.  A few points:

 - Avoid unnecessary line rewrapping.  This file gets formatted into
   HTML or manpage and formatting tools will take care of filling
   paragraphs.

 - Use "an empty string", which is used by other parts of this file
   and other documentation files under Documentaiton/config/
   directory, instead of "empty value".  We should fix other
   instances of "empty value" in the file for consistency but it
   should be left outside the scope of this patch as #leftoverbits
   material.

Thanks again.

diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 2d4e0c9b86..bd04ca1c2e 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -82,12 +82,16 @@ http.cookieFile::
 	in the Git http session, if they match the server. The file format
 	of the file to read cookies from should be plain HTTP headers or
 	the Netscape/Mozilla cookie file format (see `curl(1)`).
+	Set it to an empty string, to accept only new cookies from
+	the server and send them back in successive requests within same
+	connection.
 	NOTE that the file specified with http.cookieFile is used only as
 	input unless http.saveCookies is set.
 
 http.saveCookies::
 	If set, store cookies received during requests to the file specified by
-	http.cookieFile. Has no effect if http.cookieFile is unset.
+	http.cookieFile. Has no effect if http.cookieFile is unset, or set to
+	an empty string.
 
 http.version::
 	Use the specified HTTP protocol version when communicating with a server.
diff mbox series

Patch

diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 2d4e0c9b869..e71ca11c10b 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -78,16 +78,18 @@  http.extraHeader::
 
 http.cookieFile::
 	The pathname of a file containing previously stored cookie lines,
-	which should be used
-	in the Git http session, if they match the server. The file format
-	of the file to read cookies from should be plain HTTP headers or
-	the Netscape/Mozilla cookie file format (see `curl(1)`).
-	NOTE that the file specified with http.cookieFile is used only as
-	input unless http.saveCookies is set.
+	which should be used in the Git http session, if they match the server.
+	The file format of the file to read cookies from should be plain HTTP
+	headers or the Netscape/Mozilla cookie file format (see `curl(1)`).
+	Set it to empty value (''), to accept only new cookies from the server and
+	send them back in successive requests within same connection. NOTE that the
+	file specified with http.cookieFile is used only as input unless
+	http.saveCookies is set.
 
 http.saveCookies::
 	If set, store cookies received during requests to the file specified by
-	http.cookieFile. Has no effect if http.cookieFile is unset.
+	http.cookieFile. Has no effect if http.cookieFile is not set or set to empty
+	value ('').
 
 http.version::
 	Use the specified HTTP protocol version when communicating with a server.