[0/4] Documentation updates to FAQ and git-archive

Message

brian m. carlson Feb. 27, 2021, 7:18 p.m. UTC

This series introduces several new FAQ items and an update to the
git-archive documentation.

The first three patches introduce FAQ entries for questions I've seen
extremely frequently on Stack Overflow.  Since clearly users are seeing
these problems, we should update our documentation to address them and
help users find clear and accurate solutions.

I realize that suggesting people share a working tree across systems is
controversial, but people are doing it, so let's tell them how to do it
safely.  Users frequently use things like Dropbox, OneDrive, iCloud, and
similar cloud syncing services to do this and then wonder why things are
broken or their repository is corrupted.  We tell them that
POSIX-compliant file systems should be used and give examples of what we
know does and doesn't work, and we tell them about the security pitfalls
of untrusted working trees.

The third patch addresses several common situations with HTTP pushes and
fetches.  The majority of these problems are going to be with TLS MITM
devices, intercepting and filtering proxies of various sorts, and
non-default antivirus and firewalls, all of which security experts
steadfastly recommend against.  We don't do so here (yet), but we do
explicitly call them out as potential sources of problems and we
encourage users to report these problems to vendors and network
administrators so that they can be addressed.

The fourth patch states a fact which we've been explicit about on the
list but have never documented: that the output of git archive is not
stable.  I do recall that I sent a patch breaking kernel.org's
infrastructure in the past due to a change in archive output and I'd
like to avoid other folks relying on bit-for-bit identical output.

brian m. carlson (4):
  docs: add a question on syncing repositories to the FAQ
  docs: add line ending configuration article to FAQ
  docs: add a FAQ section on push and fetch problems
  docs: note that archives are not stable

 Documentation/git-archive.txt |   3 +
 Documentation/gitfaq.txt      | 176 +++++++++++++++++++++++++++++++++-
 2 files changed, 178 insertions(+), 1 deletion(-)