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

[Eric Sunshine <sunshine@sunshineco.com>]

On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson
<sandals@crustytoothpaste.net> wrote:
> 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
> Windows issue tracker and on Stack Overflow, and recommend against the
> use of such software.

A couple minor comments; may not be worth a reroll or discussion...

> Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
> ---
> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt
> +[[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`.  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`.

I've seen this come up on the mailing list a couple times recently,
though I haven't really followed along and don't use Git through an
SSH proxy, thus I did have to go do some reading to understand what
this is talking about. Perhaps people searching out this FAQ entry
will already have sufficient context to understand what this is
saying, so maybe no additional context is needed here. However, I was
wondering if it might make sense for this to give a bit of reason
explaining _why_ these tools need to be configured to not exit
immediately upon EOF. As it stands now, this solution is a black box;
it will work but people won't understand why. Perhaps that doesn't
matter since most people consulting a FAQ like this probably just want
to get the thing working and don't care about the underlying details.
Then again, if the underlying reason is made more readily apparent,
maybe this knowledge can become more widespread.

> +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

"modify, tamper with, change" sounds like it came from the Department
of Redundancy Department. I like the sound of "tamper with" since the
image it conveys feels quite suitable here. Perhaps this could be
simplified to:

   The proxy cannot tamper with or buffer the...

> +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.