[0/4] Additional FAQ entries

Message

brian m. carlson Oct. 20, 2021, 1:06 a.m. UTC

This series introduces some additional Git FAQ entries on various
topics.  They are all things I've seen in my professional life or on
Stack Overflow, and I tire of repeating myself, so I've written
documentation.

The first covers monorepos.  It tries to strike a neutral tone and
indicate that we're improving support for them, but it does note that
many large users still run into scale problems, especially at a point
where it's inconvenient to change[0].  I do frequently see these problems
on some scale, so my hope is that we can make users consider this case
carefully.  I have mentioned only scalability features which are
released and reasonably mature, but if I've missed any that I should
have mentioned, please let me know, since I don't always follow the list
as closely as I should.

The second covers proxies, in the generic sense of that word.  It
instructs users how to use an HTTP proxy intentionally, and it also
notes that any proxy which buffers or tampers with the data will break
Git.  I frequently see users with TLS middleboxes or antivirus software
other than the Windows default with breakage on Stack Overflow[1], and
we see them occasionally on the list as well.  Because these tools are
known to cause both functionality and security problems, both for Git
and in general[2][3][4], we explicitly recommend against them here.  I
am happy to provide additional citations to Project Zero, various bug
reports, security experts, and the cryptographic literature if folks
have doubts about whether this is the right approach.

The third should be relatively uncontroversial.  We discuss using eol
attributes in gitattributes, which we had neglected to cover before, and
illustrate their utility.  In addition, we fix a reference.

The fourth and final patch covers syncing working trees.  An earlier
version of this patch has come up on the list before and I had never
sent a rerolled version.  I realize that we don't love that people want
to do this, but users are currently using cloud syncing services and
experiencing data loss, so I figured we'd better tell them how to do it
as safely as they can so they stop losing data.

I realize that folks are busy with the Contributor Summit and other
things, and so of course reviews may be delayed.  I've tried to pick
people who I think will have relevant interest in each of these areas,
but of course feedback from anyone is welcome.

[0] For instance, the Windows repo.
[1] In addition to users for whom SSH "magically" works when HTTPS does
    not, many of which are likely the same issue.
[2] https://robert.ocallahan.org/2017/01/disable-your-antivirus-software-except.html
[3] https://twitter.com/parityzero/status/826489070310207489
[4] https://groups.google.com/g/mozilla.dev.platform/c/Bh8U0DLHrCc

brian m. carlson (4):
  gitfaq: add advice on monorepos
  gitfaq: add documentation on proxies
  gitfaq: give advice on using eol attribute in gitattributes
  gitfaq: add entry about syncing working trees

 Documentation/gitfaq.txt | 107 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 101 insertions(+), 6 deletions(-)