Re: [PATCH v2 1/3] gitfaq: add documentation on proxies

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Jan 4, 2022, 13:40 UTC
Message-ID: <nycvar.QRO.7.76.6.2201041427550.7076@tvgsbejvaqbjf.bet>
In-Reply-To: <20211107225525.431138-2-sandals@crustytoothpaste.net>

Hi brian,

On Sun, 7 Nov 2021, brian m. carlson wrote:

Show 5 quoted lines

> Many corporate environments and local systems have proxies in use.  Note
> the situations in which proxies can be used and how to configure them.
> At the same time, note what standards a proxy must follow to work with
> Git.  Explicitly call out certain classes that are known to routinely
> have problems reported various places online, including in the Git for

Not a big issue, but I think there is an "at" or "to" missing before "various places online".

Show 27 quoted lines

> Windows issue tracker and on Stack Overflow, and recommend against the
> use of such software.
>
> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
>  Documentation/gitfaq.txt | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
>
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> index 946691c153..5c21951f7b 100644
> --- a/Documentation/gitfaq.txt
> +++ b/Documentation/gitfaq.txt
> @@ -241,6 +241,29 @@ How do I know if I want to do a fetch or a pull?::
>  	ignore the upstream changes.  A pull consists of a fetch followed
>  	immediately by either a merge or rebase.  See linkgit:git-pull[1].
>
> +[[proxy]]
> +Can I use a proxy with Git?::
> +	Yes, Git supports the use of proxies.  Git honors the standard `http_proxy`,
> +	`https_proxy`, and `no_proxy` environment variables commonly used on Unix, and
> +	it also can be configured with `http.proxy` and similar options for HTTPS (see
> +	linkgit:git-config[1]).  The `http.proxy` and related options can be
> +	customized on a per-URL pattern basis.  In addition, Git can in theory
> +	function normally with transparent proxies that exist on the network.
> ++
> +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools
> +include `netcat` and `socat`.

The first idea I had after reading this is: where are these examples documented? Certainly not where I expected them, namely at https://git-scm.com/docs/git-config#Documentation/git-config.txt-coregitProxy

And then I got puzzled. Why would `gitproxy` be used for the _SSH_ protocol? And I don't think it is used. I think it is only used for connections using the `git://` protocol. I might very easily be wrong, of course.

> However, they must be configured not to exit when +seeing EOF on
> standard input, which usually means that `netcat` will require +`-q` and
> `socat` will require a timeout with something like `-t 10`.

IMHO it would make sense to add a concrete example, or maybe even two concrete examples, one for `netcat` and one for `socat`.

Show 10 quoted lines

> ++
> +Note that in all cases, for Git to work properly, the proxy must be completely
> +transparent.  The proxy cannot modify, tamper with, change, or buffer the
> +connection in any way, or Git will almost certainly fail to work.  Note that
> +many proxies, including many TLS middleboxes, Windows antivirus and firewall
> +programs other than Windows Defender and Windows Firewall, and filtering proxies
> +fail to meet this standard, and as a result end up breaking Git.  Because of the
> +many reports of problems, we recommend against the use of these classes of
> +software and devices.
> +

This is good advice.

Ciao, Dscho