{"thread":{"id":"56857","subject":"[PATCH v2 1/3] gitfaq: add documentation on proxies","startedAt":"2021-11-07T22:56:22Z","lastAt":"2022-01-06T01:58:44Z","messageCount":19,"participants":["brian m. carlson","Eric Sunshine","Junio C Hamano","Johannes Schindelin"],"isPatch":true,"patchVersion":2,"patchTotal":3},"messages":[{"id":"440646","messageId":"20211107225525.431138-2-sandals@crustytoothpaste.net","threadId":"56857","inReplyTo":"20211107225525.431138-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 1/3] gitfaq: add documentation on proxies","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-07T22:55:23Z","receivedAt":"2021-11-07T22:56:22Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Many corporate environments and local systems have proxies in use. Note\nthe situations in which proxies can be used and how to configure them.\nAt the same time, note what standards a proxy must follow to work with\nGit. Explicitly call out certain classes that are known to routinely\nhave problems reported various places online, including in the Git for\nWindows issue tracker and on Stack Overflow, and recommend against the\nuse of such software.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/gitfaq.txt | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 946691c153..5c21951f7b 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -241,6 +241,29 @@ How do I know if I want to do a fetch or a pull?::\n \tignore the upstream changes. A pull consists of a fetch followed\n \timmediately by either a merge or rebase. See linkgit:git-pull[1].\n \n+[[proxy]]\n+Can I use a proxy with Git?::\n+\tYes, Git supports the use of proxies. Git honors the standard `http_proxy`,\n+\t`https_proxy`, and `no_proxy` environment variables commonly used on Unix, and\n+\tit also can be configured with `http.proxy` and similar options for HTTPS (see\n+\tlinkgit:git-config[1]). The `http.proxy` and related options can be\n+\tcustomized on a per-URL pattern basis. In addition, Git can in theory\n+\tfunction normally with transparent proxies that exist on the network.\n++\n+For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools\n+include `netcat` and `socat`. However, they must be configured not to exit when\n+seeing EOF on standard input, which usually means that `netcat` will require\n+`-q` and `socat` will require a timeout with something like `-t 10`.\n++\n+Note that in all cases, for Git to work properly, the proxy must be completely\n+transparent. The proxy cannot modify, tamper with, change, or buffer the\n+connection in any way, or Git will almost certainly fail to work. Note that\n+many proxies, including many TLS middleboxes, Windows antivirus and firewall\n+programs other than Windows Defender and Windows Firewall, and filtering proxies\n+fail to meet this standard, and as a result end up breaking Git. Because of the\n+many reports of problems, we recommend against the use of these classes of\n+software and devices.\n+\n Design\n ------\n \n"},{"id":"440647","messageId":"20211107225525.431138-4-sandals@crustytoothpaste.net","threadId":"56857","inReplyTo":"20211107225525.431138-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-07T22:55:25Z","receivedAt":"2021-11-07T22:56:22Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Users very commonly want to sync their working tree with uncommitted\nchanges across machines, often to carry across in-progress work or\nstashes. Despite this not being a recommended approach, users want to\ndo it and are not dissuaded by suggestions not to, so let's recommend a\nsensible technique.\n\nThe technique that many users are using is their preferred cloud syncing\nservice, which is a bad idea. Users have reported problems where they\nend up with duplicate files that won't go away (with names like \"file.c\n2\"), broken references, oddly named references that have date stamps\nappended to them, missing objects, and general corruption and data loss.\nThat's because almost all of these tools sync file by file, which is a\ngreat technique if your project is a single word processing document or\nspreadsheet, but is utterly abysmal for Git repositories because they\ndon't necessarily snapshot the entire repository correctly. They also\ntend to sync the files immediately instead of when the repository is\nquiescent, so writing multiple files, as occurs during a commit or a gc,\ncan confuse the tools and lead to corruption.\n\nWe know that the old standby, rsync, is up to the task, provided that\nthe repository is quiescent, so let's suggest that and dissuade people\nfrom using cloud syncing tools. Let's tell people about common things\nthey should be aware of before doing this and that this is still\npotentially risky. Additionally, let's tell people that Git's security\nmodel does not permit sharing working trees across users in case they\nplanned to do that. While we'd still prefer users didn't try to do\nthis, hopefully this will lead them in a safer direction.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/gitfaq.txt | 47 ++++++++++++++++++++++++++++++++++++++--\n 1 file changed, 45 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex ae1b526565..e5dab89d6c 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -83,8 +83,8 @@ Windows would be the configuration `\"C:\\Program Files\\Vim\\gvim.exe\" --nofork`,\n which quotes the filename with spaces and specifies the `--nofork` option to\n avoid backgrounding the process.\n \n-Credentials\n------------\n+Credentials and Transfers\n+-------------------------\n \n [[http-credentials]]\n How do I specify my credentials when pushing over HTTP?::\n@@ -185,6 +185,49 @@ Then, you can adjust your push URL to use `git@example_author` or\n `git@example_committer` instead of `git@example.org` (e.g., `git remote set-url\n git@example_author:org1/project1.git`).\n \n+[[sync-working-tree]]\n+How do I sync a working tree across systems?::\n+\tFirst, decide whether you want to do this at all. Git usually works better\n+\twhen you push or pull your work using the typical `git push` and `git fetch`\n+\tcommands and isn't designed to share a working tree across systems. This is\n+\tpotentially risky and in some cases can cause repository corruption or data\n+\tloss.\n++\n+Usually, doing so will cause `git status` to need to re-read every file in the\n+working tree. Additionally, Git's security model does not permit sharing a\n+working tree across untrusted users, so it is only safe to sync a working tree\n+if it will only be used by a single user across all machines.\n++\n+It is important not to use a cloud syncing service to sync any portion of a Git\n+repository, since this can cause corruption, such as missing objects, changed\n+or added files, broken refs, and a wide variety of other corruption. These\n+services tend to sync file by file and don't understand the structure of a Git\n+repository. This is especially bad if they sync the repository in the middle of\n+it being updated, since that is very likely to cause incomplete or partial\n+updates and therefore data loss.\n++\n+Therefore, it's better to push your work to either the other system or a central\n+server using the normal push and pull mechanism. However, this doesn't always\n+preserve important data, like stashes, so some people prefer to share a working\n+tree across systems.\n++\n+If you do this, the recommended approach is to use `rsync -a --delete-after`\n+(ideally with an encrypted connection such as with `ssh`) on the root of\n+repository. You should ensure several things when you do this:\n++\n+* There are no additional worktrees enabled for your repository.\n+* You are not using a separate Git directory outside of your repository root.\n+* You are comfortable with the destination directory being an exact copy of the\n+\tsource directory, _deleting any data that is already there_.\n+* The repository is in a quiescent state for the duration of the transfer (that\n+\tis, no operations of any sort are taking place on it, including background\n+\toperations like `git gc` and operations invoked by your editor).\n++\n+Be aware that even with these recommendations, syncing in this way has some risk\n+since it bypasses Git's normal integrity checking for repositories, so having\n+backups is advised. You may also with to do a `git fsck` to verify the\n+integrity of your data on the destination system after syncing.\n+\n Common Issues\n -------------\n \n"},{"id":"440648","messageId":"20211107225525.431138-1-sandals@crustytoothpaste.net","threadId":"56857","inReplyTo":null,"subject":"[PATCH v2 0/3] Additional FAQ entries","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-07T22:55:22Z","receivedAt":"2021-11-07T22:56:30Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"This series introduces some additional Git FAQ entries on various\ntopics. They are all things I've seen in my professional life or on\nStack Overflow, so I've written documentation.\n\nI've opted not to include backing up repositories in the syncing patch\nbecause I think they're separate topics. We could well end up with an\nadditional FAQ entry on that topic, which is left as an exercise for the\nreader.\n\nChanges from v1:\n* Drop the monorepo patch for now; I want to revise it further.\n* Reorder the working tree patch to place more warnings up front.\n* Mention core.gitproxy and socat.\n* Rephrase text in the EOL entry to read correctly and be easier to\n understand.\n* Improve the commit message for the working tree FAQ entry to make it\n clearer that users wish to transfer uncommitted changes.\n\nbrian m. carlson (3):\n gitfaq: add documentation on proxies\n gitfaq: give advice on using eol attribute in gitattributes\n gitfaq: add entry about syncing working trees\n\n Documentation/gitfaq.txt | 90 +++++++++++++++++++++++++++++++++++++---\n 1 file changed, 84 insertions(+), 6 deletions(-)\n\n"},{"id":"440649","messageId":"20211107225525.431138-3-sandals@crustytoothpaste.net","threadId":"56857","inReplyTo":"20211107225525.431138-1-sandals@crustytoothpaste.net","subject":"[PATCH v2 2/3] gitfaq: give advice on using eol attribute in gitattributes","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-07T22:55:24Z","receivedAt":"2021-11-07T22:56:31Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"In the FAQ, we tell people how to use the text attribute, but we fail to\nexplain what to do with the eol attribute. As we ourselves have\nnoticed, most shell implementations do not care for carriage returns,\nand as such, people will practically always want them to use LF endings.\nSimilar things can be said for batch files on Windows, except with CRLF\nendings.\n\nSince these are common things to have in a repository, let's help users\nmake a good decision by recommending that they use the gitattributes\nfile to correctly check out the endings.\n\nIn addition, let's correct the cross-reference to this question, which\noriginally referred to \"the following entry\", even though a new entry\nhas been inserted in between. The cross-reference notation should\nprevent this from occurring and provide a link in formats, such as HTML,\nwhich support that.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/gitfaq.txt | 20 ++++++++++++++++----\n 1 file changed, 16 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\nindex 5c21951f7b..ae1b526565 100644\n--- a/Documentation/gitfaq.txt\n+++ b/Documentation/gitfaq.txt\n@@ -406,8 +406,9 @@ I'm on Windows and git diff shows my files as having a `^M` at the end.::\n +\n You can store the files in the repository with Unix line endings and convert\n them automatically to your platform's line endings. To do that, set the\n-configuration option `core.eol` to `native` and see the following entry for\n-information about how to configure files as text or binary.\n+configuration option `core.eol` to `native` and see\n+<>\n+for information about how to configure files as text or binary.\n +\n You can also control this behavior with the `core.whitespace` setting if you\n don't wish to remove the carriage returns from your line endings.\n@@ -469,14 +470,25 @@ references, URLs, and hashes stored in the repository.\n +\n We also recommend setting a linkgit:gitattributes[5] file to explicitly mark\n which files are text and which are binary. If you want Git to guess, you can\n-set the attribute `text=auto`. For example, the following might be appropriate\n-in some projects:\n+set the attribute `text=auto`.\n++\n+With text files, Git will generally ensure that LF endings are used in the\n+repository, and will honor `core.autocrlf` and `core.eol` to decide what options\n+to use when checking files out. You can also override this by specifying a\n+particular line ending such as `eol=lf` or `eol=crlf` if those files must always\n+have that ending in the working tree (e.g., for functionality reasons).\n++\n+For example, the following might be appropriate in some projects:\n +\n ----\n # By default, guess.\n *\ttext=auto\n # Mark all C files as text.\n *.c\ttext\n+# Ensure all shell files end up with LF endings and all batch files end up\n+# with CRLF endings in the working tree and both end up with LF in the repo.\n+*.sh text eol=lf\n+*.bat text eol=crlf\n # Mark all JPEG files as binary.\n *.jpg\tbinary\n ----\n"},{"id":"440650","messageId":"CAPig+cT5bU3K9aUk=Y6YAOJjAmDvOWitYD_jtgHap_BYs2mPgA@mail.gmail.com","threadId":"56857","inReplyTo":"20211107225525.431138-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 1/3] gitfaq: add documentation on proxies","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-11-07T23:27:24Z","receivedAt":"2021-11-07T23:27:38Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson\n wrote:\n> Many corporate environments and local systems have proxies in use. Note\n> the situations in which proxies can be used and how to configure them.\n> At the same time, note what standards a proxy must follow to work with\n> Git. Explicitly call out certain classes that are known to routinely\n> have problems reported various places online, including in the Git for\n> Windows issue tracker and on Stack Overflow, and recommend against the\n> use of such software.\n\nA couple minor comments; may not be worth a reroll or discussion...\n\n> Signed-off-by: brian m. carlson \n> ---\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> +[[proxy]]\n> +Can I use a proxy with Git?::\n> + Yes, Git supports the use of proxies. Git honors the standard `http_proxy`,\n> + `https_proxy`, and `no_proxy` environment variables commonly used on Unix, and\n> + it also can be configured with `http.proxy` and similar options for HTTPS (see\n> + linkgit:git-config[1]). The `http.proxy` and related options can be\n> + customized on a per-URL pattern basis. In addition, Git can in theory\n> + function normally with transparent proxies that exist on the network.\n> ++\n> +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools\n> +include `netcat` and `socat`. However, they must be configured not to exit when\n> +seeing EOF on standard input, which usually means that `netcat` will require\n> +`-q` and `socat` will require a timeout with something like `-t 10`.\n\nI've seen this come up on the mailing list a couple times recently,\nthough I haven't really followed along and don't use Git through an\nSSH proxy, thus I did have to go do some reading to understand what\nthis is talking about. Perhaps people searching out this FAQ entry\nwill already have sufficient context to understand what this is\nsaying, so maybe no additional context is needed here. However, I was\nwondering if it might make sense for this to give a bit of reason\nexplaining _why_ these tools need to be configured to not exit\nimmediately upon EOF. As it stands now, this solution is a black box;\nit will work but people won't understand why. Perhaps that doesn't\nmatter since most people consulting a FAQ like this probably just want\nto get the thing working and don't care about the underlying details.\nThen again, if the underlying reason is made more readily apparent,\nmaybe this knowledge can become more widespread.\n\n> +Note that in all cases, for Git to work properly, the proxy must be completely\n> +transparent. The proxy cannot modify, tamper with, change, or buffer the\n> +connection in any way, or Git will almost certainly fail to work. Note that\n\n\"modify, tamper with, change\" sounds like it came from the Department\nof Redundancy Department. I like the sound of \"tamper with\" since the\nimage it conveys feels quite suitable here. Perhaps this could be\nsimplified to:\n\n The proxy cannot tamper with or buffer the...\n\n> +many proxies, including many TLS middleboxes, Windows antivirus and firewall\n> +programs other than Windows Defender and Windows Firewall, and filtering proxies\n> +fail to meet this standard, and as a result end up breaking Git. Because of the\n> +many reports of problems, we recommend against the use of these classes of\n> +software and devices.\n"},{"id":"440651","messageId":"CAPig+cRkbjt=bJngcbzVPRGqY=14Zs57V0i=RR_5=m+k8fu+hg@mail.gmail.com","threadId":"56857","inReplyTo":"20211107225525.431138-3-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 2/3] gitfaq: give advice on using eol attribute in gitattributes","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-11-07T23:48:00Z","receivedAt":"2021-11-07T23:48:13Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson\n wrote:\n> In the FAQ, we tell people how to use the text attribute, but we fail to\n> explain what to do with the eol attribute. As we ourselves have\n> noticed, most shell implementations do not care for carriage returns,\n> and as such, people will practically always want them to use LF endings.\n> Similar things can be said for batch files on Windows, except with CRLF\n> endings.\n>\n> Since these are common things to have in a repository, let's help users\n> make a good decision by recommending that they use the gitattributes\n> file to correctly check out the endings.\n> [...]\n> Signed-off-by: brian m. carlson \n> ---\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> @@ -469,14 +470,25 @@ references, URLs, and hashes stored in the repository.\n> +With text files, Git will generally ensure that LF endings are used in the\n> +repository, and will honor `core.autocrlf` and `core.eol` to decide what options\n> +to use when checking files out. You can also override this by specifying a\n> +particular line ending such as `eol=lf` or `eol=crlf` if those files must always\n> +have that ending in the working tree (e.g., for functionality reasons).\n> ++\n> +For example, the following might be appropriate in some projects:\n> +\n> ----\n> # By default, guess.\n> * text=auto\n> # Mark all C files as text.\n> *.c text\n> +# Ensure all shell files end up with LF endings and all batch files end up\n> +# with CRLF endings in the working tree and both end up with LF in the repo.\n> +*.sh text eol=lf\n> +*.bat text eol=crlf\n> # Mark all JPEG files as binary.\n> *.jpg binary\n> ----\n\nI like the concrete explanation in the commit message of why `.sh` and\n`.bat` files need to be configured specially, and was expecting that\nquite useful information to be repeated here in the body. That does\nseem exactly like what someone would come to the FAQ searching for,\nand even though the above content hints at it, the hint may be just\nvague enough to be overlooked. Consequently, I'm wondering if it ought\nto be spelled out more explicitly here. In particular, if we give\nexamples of actual error messages people might encounter when\nattempting to run a CRLF shell script or an LF batch file, that would\nreally give a FAQ searcher/reader something to latch onto when trying\nto solve a problem. This could be done as a lead-in paragraph\nimmediately before the \"For example, the following...\".\n\nAlso, following v1 review, I think you had intended[1]: s/end up with/have/\n\n[1]: https://lore.kernel.org/git/YW9wgbN%2Fb8NkVp4z@camp.crustytoothpaste.net/\n"},{"id":"440652","messageId":"CAPig+cRtOpaPd_HCQAW=33-vxhP4Knijo3g0dUA9HVb4_=JH4w@mail.gmail.com","threadId":"56857","inReplyTo":"20211107225525.431138-4-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-11-08T00:12:14Z","receivedAt":"2021-11-08T00:12:27Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson\n wrote:\n> Users very commonly want to sync their working tree with uncommitted\n> changes across machines, often to carry across in-progress work or\n> stashes. Despite this not being a recommended approach, users want to\n> do it and are not dissuaded by suggestions not to, so let's recommend a\n> sensible technique.\n> [...]\n> Signed-off-by: brian m. carlson \n> ---\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> @@ -185,6 +185,49 @@ Then, you can adjust your push URL to use `git@example_author` or\n> +[[sync-working-tree]]\n> +How do I sync a working tree across systems?::\n> + First, decide whether you want to do this at all. Git usually works better\n> + when you push or pull your work using the typical `git push` and `git fetch`\n> + commands and isn't designed to share a working tree across systems. This is\n> + potentially risky and in some cases can cause repository corruption or data\n> + loss.\n\nThe phrase \"usually works better\" makes this statement feel weak, thus\nit may not convey the potential severity of the issue. I wonder if\nrewording it something like this would make the statement more\nforceful:\n\n Git works best when you `git push` and `git pull` your work\n between machines; it is not designed to share a working tree\n across systems. [...]\n\n> +Usually, doing so will cause `git status` to need to re-read every file in the\n> +working tree. Additionally, Git's security model does not permit sharing a\n> +working tree across untrusted users, so it is only safe to sync a working tree\n> +if it will only be used by a single user across all machines.\n> ++\n> +It is important not to use a cloud syncing service to sync any portion of a Git\n> +repository, since this can cause corruption, such as missing objects, changed\n> +or added files, broken refs, and a wide variety of other corruption. These\n> +services tend to sync file by file and don't understand the structure of a Git\n> +repository. This is especially bad if they sync the repository in the middle of\n> +it being updated, since that is very likely to cause incomplete or partial\n> +updates and therefore data loss.\n\nTaking into consideration that people who are experiencing such\ncorruption will likely include the name of the syncing service in\ntheir search query, would it make sense to mention some well-known\nservices here in order to make it more likely that people will\nactually find this entry? Something like this, perhaps:\n\n It is important not to use a cloud syncing service (such as DropBox,\n FooBar, CowMoo, BuzzingBee, etc.) to sync any portion of a Git\n repository...\n\n> +Therefore, it's better to push your work to either the other system or a central\n> +server using the normal push and pull mechanism. However, this doesn't always\n> +preserve important data, like stashes, so some people prefer to share a working\n> +tree across systems.\n> ++\n> +If you do this, the recommended approach is to use `rsync -a --delete-after`\n> +(ideally with an encrypted connection such as with `ssh`) on the root of\n> +repository. You should ensure several things when you do this:\n> ++\n> +* There are no additional worktrees enabled for your repository.\n\nI don't fully understand this restriction. Can you explain it (at\nleast here in the email discussion)?\n\n> +* You are not using a separate Git directory outside of your repository root.\n\nSame question about this restriction.\n\n> +* You are comfortable with the destination directory being an exact copy of the\n> + source directory, _deleting any data that is already there_.\n> +* The repository is in a quiescent state for the duration of the transfer (that\n> + is, no operations of any sort are taking place on it, including background\n> + operations like `git gc` and operations invoked by your editor).\n> ++\n> +Be aware that even with these recommendations, syncing in this way has some risk\n> +since it bypasses Git's normal integrity checking for repositories, so having\n> +backups is advised. You may also with to do a `git fsck` to verify the\n> +integrity of your data on the destination system after syncing.\n\ns/with/wish/\n\nIn fact, as with \"usually\" above, \"wish\" may be too weak. Perhaps say\ninstead that it is \"recommended\" that you use `git fsck` to verify the\nintegrity.\n"},{"id":"440653","messageId":"CAPig+cTWwmVFggD2UL=Ddd3rc007zRWcRs7nQtEHSS5kgjx4og@mail.gmail.com","threadId":"56857","inReplyTo":"20211107225525.431138-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/3] Additional FAQ entries","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-11-08T00:16:04Z","receivedAt":"2021-11-08T00:16:19Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson\n wrote:\n> This series introduces some additional Git FAQ entries on various\n> topics. They are all things I've seen in my professional life or on\n> Stack Overflow, so I've written documentation.\n>\n> Changes from v1:\n> * Drop the monorepo patch for now; I want to revise it further.\n> * Reorder the working tree patch to place more warnings up front.\n> * Mention core.gitproxy and socat.\n> * Rephrase text in the EOL entry to read correctly and be easier to\n> understand.\n> * Improve the commit message for the working tree FAQ entry to make it\n> clearer that users wish to transfer uncommitted changes.\n\nThanks for re-rolling. FAQ entries are, of course, bikeshedding\nfodder, so I left a number of bikeshedding comments and pointed out\none minor typo. Whether any of the comments warrant a re-roll or are\neven worth discussing is a matter of opinion, and they could certainly\nall be addressed later (by someone) atop the current series if\ndesired; I don't think any of the comments were blockers.\n"},{"id":"440658","messageId":"YYiDGhkaaQq7gpLK@camp.crustytoothpaste.net","threadId":"56857","inReplyTo":"CAPig+cT5bU3K9aUk=Y6YAOJjAmDvOWitYD_jtgHap_BYs2mPgA@mail.gmail.com","subject":"Re: [PATCH v2 1/3] gitfaq: add documentation on proxies","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-08T01:53:30Z","receivedAt":"2021-11-08T01:53:36Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-11-07 at 23:27:24, Eric Sunshine wrote:\n> I've seen this come up on the mailing list a couple times recently,\n> though I haven't really followed along and don't use Git through an\n> SSH proxy, thus I did have to go do some reading to understand what\n> this is talking about. Perhaps people searching out this FAQ entry\n> will already have sufficient context to understand what this is\n> saying, so maybe no additional context is needed here. However, I was\n> wondering if it might make sense for this to give a bit of reason\n> explaining _why_ these tools need to be configured to not exit\n> immediately upon EOF. As it stands now, this solution is a black box;\n> it will work but people won't understand why. Perhaps that doesn't\n> matter since most people consulting a FAQ like this probably just want\n> to get the thing working and don't care about the underlying details.\n> Then again, if the underlying reason is made more readily apparent,\n> maybe this knowledge can become more widespread.\n\nI'll try to see if I can stuff in a sentence there about why that's\nnecessary. I think I understand it sufficiently well to summarize it.\n\n> \"modify, tamper with, change\" sounds like it came from the Department\n> of Redundancy Department. I like the sound of \"tamper with\" since the\n> image it conveys feels quite suitable here. Perhaps this could be\n> simplified to:\n> \n> The proxy cannot tamper with or buffer the...\n\nI realize this sounds redundant, but I'm trying to avoid the situation\nwhere people say, \"I'm not _tampering_ with it, since I'm authorized to\ndo this by the company. I'm just modifying it to remove this\ninappropriate content/malware/data leak.\" My goal here is to make it\ncrystal clear that if you do this, you'll break things, and provide\nammunition for people to go to their IT departments and say, \"Look, your\nproxy prevents me from doing my job. The Git developers say so. Fix\nit.\"\n\nI can drop one of \"change\" and \"modify\", though, since I think they're\nsynonyms.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"},{"id":"440659","messageId":"YYiG7rTkElKbucl0@camp.crustytoothpaste.net","threadId":"56857","inReplyTo":"CAPig+cRkbjt=bJngcbzVPRGqY=14Zs57V0i=RR_5=m+k8fu+hg@mail.gmail.com","subject":"Re: [PATCH v2 2/3] gitfaq: give advice on using eol attribute in gitattributes","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-08T02:09:50Z","receivedAt":"2021-11-08T02:09:57Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-11-07 at 23:48:00, Eric Sunshine wrote:\n> I like the concrete explanation in the commit message of why `.sh` and\n> `.bat` files need to be configured specially, and was expecting that\n> quite useful information to be repeated here in the body. That does\n> seem exactly like what someone would come to the FAQ searching for,\n> and even though the above content hints at it, the hint may be just\n> vague enough to be overlooked. Consequently, I'm wondering if it ought\n> to be spelled out more explicitly here. In particular, if we give\n> examples of actual error messages people might encounter when\n> attempting to run a CRLF shell script or an LF batch file, that would\n> really give a FAQ searcher/reader something to latch onto when trying\n> to solve a problem. This could be done as a lead-in paragraph\n> immediately before the \"For example, the following...\".\n\nI think that we could definitely add some text here to explain why one\nwould want to use this, providing an example.\n\n> Also, following v1 review, I think you had intended[1]: s/end up with/have/\n\nI will fix that in v3. Thanks for the reminder.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"},{"id":"440690","messageId":"xmqqbl2utk6a.fsf@gitster.g","threadId":"56857","inReplyTo":"YYiDGhkaaQq7gpLK@camp.crustytoothpaste.net","subject":"Re: [PATCH v2 1/3] gitfaq: add documentation on proxies","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-08T21:24:45Z","receivedAt":"2021-11-08T21:24:51Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> I realize this sounds redundant, but I'm trying to avoid the situation\n> where people say, \"I'm not _tampering_ with it, since I'm authorized to\n> do this by the company. I'm just modifying it to remove this\n> inappropriate content/malware/data leak.\"\n\nIt might be a good strategy to educate users by leaving a deliberate\nhole to let them quibble with such an excuse. When it comes to\non-the-wire protocol, their management do not have authority to\ngrant them right to tamper with the data and that is not limited to\nGit.\n\n\n"},{"id":"440693","messageId":"xmqqmtmes3ix.fsf@gitster.g","threadId":"56857","inReplyTo":"CAPig+cRtOpaPd_HCQAW=33-vxhP4Knijo3g0dUA9HVb4_=JH4w@mail.gmail.com","subject":"Re: [PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-08T22:09:42Z","receivedAt":"2021-11-08T22:09:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> Taking into consideration that people who are experiencing such\n> corruption will likely include the name of the syncing service in\n> their search query, would it make sense to mention some well-known\n> services here in order to make it more likely that people will\n> actually find this entry? Something like this, perhaps:\n>\n> It is important not to use a cloud syncing service (such as DropBox,\n> FooBar, CowMoo, BuzzingBee, etc.) to sync any portion of a Git\n> repository...\n\nI do agree that in a repository being actively modified, any\nbackup/sync solution that works per-file fashion would not work\nwell. But is \"cloud\" a good word to characterise and group these\nper-file backup/sync solution? \n\nDoesn't rsync work the same per-file fashion, and the only reason\nwhy it is a better fit is because it is not continuous, not\nattempting to \"sync\" while the repository is in use, until the user\nexplicitly says \"OK, I am ready to go home, so let's stop working\nhere and send everything over to home with rsync\"?\n\n>> +* There are no additional worktrees enabled for your repository.\n>\n> I don't fully understand this restriction. Can you explain it (at\n> least here in the email discussion)?\n>\n>> +* You are not using a separate Git directory outside of your repository root.\n>\n> Same question about this restriction.\n\nAs long as you know what you are doing and catch everything in\nquiescent state, you should be fine, I would think.\n"},{"id":"440707","messageId":"CAPig+cTN+ktteGYv6dm_Qr=FejiwRMGwRW9p--7s46H7sxa3JQ@mail.gmail.com","threadId":"56857","inReplyTo":"YYmmBMkwy6bpVpzI@camp.crustytoothpaste.net","subject":"Re: [PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-11-09T00:02:54Z","receivedAt":"2021-11-09T00:03:07Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Mon, Nov 8, 2021 at 5:34 PM brian m. carlson\n wrote:\n> On 2021-11-08 at 00:12:14, Eric Sunshine wrote:\n> > Taking into consideration that people who are experiencing such\n> > corruption will likely include the name of the syncing service in\n> > their search query, would it make sense to mention some well-known\n> > services here in order to make it more likely that people will\n> > actually find this entry? Something like this, perhaps:\n> >\n> > It is important not to use a cloud syncing service (such as DropBox,\n> > FooBar, CowMoo, BuzzingBee, etc.) to sync any portion of a Git\n> > repository...\n>\n> There are a lot of these services. My preference is to not name\n> specific ones here, just like we don't name specific ones when we state\n> that you shouldn't use an antivirus or firewall other than the Windows\n> default, mostly because I'm not interested in angering corporate\n> lawyers. My advice on this topic is always general: XYZ is a cloud\n> syncing service, and you should not use any cloud syncing services for Git.\n\nMy \"would it make sense\" question arose from taking into consideration\nhow people are likely to use a search engine for a particular problem:\n\n BuzzingBee syncing corrupted git repository\n\nWithout naming specific services or tools, it seems much less likely\nthat people will find this FAQ entry, thus will end up posting to\nStackOverflow (or wherever) anyhow -- despite your intention and\neffort behind the FAQ in the first place. I'm thinking about\ndiscoverability -- which is the same reason I suggested in my review\nof the other patch that it might be a good idea to add actual error\nmessages a person might encounter with a CRLF shell script or an LF\nbatch file.\n\n> Additionally, the popular options differ by region. For example, there\n> are some services which are probably popular in China which are not\n> popular elsewhere, and I don't think it's a good idea to try to guess\n> which ones happen to be most popular around the world.\n\nThe other way to look at it is that listing many popular services\n(wherever they happen to be) makes it more likely that search engines\nwill lead them to this FAQ entry and alleviate the need to post a\nquestion somewhere.\n\nAnyhow, it was just a thought. I think I've said all I have to say on\nthis subject. As I mentioned in response to the cover letter, all of\nmy comments were of the bikeshedding variety, and I didn't see any\nshow-stoppers in the series as posted.\n\n> > > +* There are no additional worktrees enabled for your repository.\n> >\n> > I don't fully understand this restriction. Can you explain it (at\n> > least here in the email discussion)?\n>\n> If you sync the main repository and working tree, but not the worktrees\n> themselves, then you end up with incorrect data in the .git directory,\n> which contains information about the worktree.\n\nI still don't follow. What incorrect data will be in the .git\ndirectory? Do you mean the absolute path pointing from the .git\ndirectory to the worktree?\n\n> More importantly, it can\n> contain absolute path information, which would be undesirable even if\n> you did sync the worktrees, say, if you used two different usernames\n> (and hence two different home directories) on the two systems.\n\nOkay, I figured that that was probably one of your concerns, but it\nwas difficult to tell from the raw \"no additional worktrees\". On the\nother hand, I can easily see people syncing between machines in which\nthey have the same username and same directory structure, so this\nbullet point seems overly restrictive.\n\n> > > +* You are not using a separate Git directory outside of your repository root.\n> >\n> > Same question about this restriction.\n>\n> Again, if you sync the root of the working tree but don't sync the\n> separate Git directory, you won't have copied the index or any of the\n> other data.\n\nOkay, again, this is indeed what I thought you might have in mind, but\nit was difficult to be sure. And, again, this seems overly restrictive\nsince there may be plenty of scenarios in which this works well.\n\nI suppose both of these points would feel more reasonable if they\ndidn't sound like hard requirements, perhaps by explaining that the\nsimple case of no worktrees and no separate repository has the least\nrestrictions and is easiest to get up and running; more complex cases\ncan work too with the caveat that worktree and separate repository\ndirectories ought to be synced too, and that pathnames need to be\nidentical on all machines.\n"},{"id":"440708","messageId":"xmqqtugm42aq.fsf@gitster.g","threadId":"56857","inReplyTo":"xmqqmtmes3ix.fsf@gitster.g","subject":"Re: [PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-11-09T00:10:05Z","receivedAt":"2021-11-09T00:10:12Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Doesn't rsync work the same per-file fashion, and the only reason\n> why it is a better fit is because it is not continuous, not\n> attempting to \"sync\" while the repository is in use, until the user\n> explicitly says \"OK, I am ready to go home, so let's stop working\n> here and send everything over to home with rsync\"?\n\nOK, so not \"per-file\" but \"continuous\" is the root problem, and\n\"cloud\" would be a good word because all the popular ones share that\n\"continuous\" trait.\n\nThis part of the proposed patch text may need rethinking a bit.\n\n> +or added files, broken refs, and a wide variety of other corruption. These\n> +services tend to sync file by file and don't understand the structure of a Git\n> +repository. This is especially bad if they sync the repository in the middle of\n\nThat is, \"file by file\" is not a problem per-se, \"don't understand\nthe structure\" is a huge problem, and \"continuous\" may contribute to\nthe problem further.\n\nI wonder if you let the \"cloud\" services to continuously sync your\nrepository, then go quiescent for a while and then start touching\nthe destination, it would be sufficient, though. The refs with\nfunny \"2\" suffixes and the like are the symptom of two sides\nsimultanously mucking with the same file (e.g \".git/refs/main\") and\nthe \"cloud sync\" could not decide what the right final outcome is,\nright?\n\nI also wonder if we add a way to transfer reflog entries, that imply\nthe object reachability, say \"git push --with-reflog\", over the\nwire, it would be sufficient to do everything with Git.\n\nBefore you go home, you'd do\n\n git stash save --untracked && git stash apply\n git push --mirror --with-reflog --with-stash\n\nto save away modified and untracked files to a stash entry [*], and push\nall the refs with their reflog entries (including refs/stash which\nnormally gets refused because it has only two levels).\n\n Side note. If there were a variant of \"git stash save\" that only\n saves away without modifying the working tree and the index, I'd\n use that single command instead of \"save and immediately restore\n by applying\" kludge.\n\nThen at the destination, you'd figure out what the current branch\nwas (the stash message should record tha name of the branch), check\nthat branch out, and running \"git stash pop\" will give you pretty\nmuch the same environment.\n"},{"id":"441103","messageId":"YZGeVtdshoip34AP@camp.crustytoothpaste.net","threadId":"56857","inReplyTo":"xmqqtugm42aq.fsf@gitster.g","subject":"Re: [PATCH v2 3/3] gitfaq: add entry about syncing working trees","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-11-14T23:40:06Z","receivedAt":"2021-11-14T23:40:42Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-11-09 at 00:10:05, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> \n> > Doesn't rsync work the same per-file fashion, and the only reason\n> > why it is a better fit is because it is not continuous, not\n> > attempting to \"sync\" while the repository is in use, until the user\n> > explicitly says \"OK, I am ready to go home, so let's stop working\n> > here and send everything over to home with rsync\"?\n> \n> OK, so not \"per-file\" but \"continuous\" is the root problem, and\n> \"cloud\" would be a good word because all the popular ones share that\n> \"continuous\" trait.\n> \n> This part of the proposed patch text may need rethinking a bit.\n> \n> > +or added files, broken refs, and a wide variety of other corruption. These\n> > +services tend to sync file by file and don't understand the structure of a Git\n> > +repository. This is especially bad if they sync the repository in the middle of\n> \n> That is, \"file by file\" is not a problem per-se, \"don't understand\n> the structure\" is a huge problem, and \"continuous\" may contribute to\n> the problem further.\n\n\"File by file\" is not a problem per se, but it is a problem if you don't\nsnapshot the repository or it's in use. For example, if you used an LVM\nsnapshot on an in-use repository and then synced that, we'd guarantee\nthat the repository was fully consistent. Practically nobody does that,\nthough.\n\nBut to clarify: the goal of this type of software is to sync single,\nindependent documents. As such, these tools don't necessarily consider\nthat it's important to sync other files in the same directory at the\nsame time. You can end up with cases where some parts of your\nrepository get synced, then some other files in other directories, then\nother parts of the repository, resulting in different states over\ndifferent times. There's just no guarantee about how they behave with\nall of the files in a given repository because they aren't considered a\nrelevant unit. That's why I mention that they sync file by file. If\nthey did syncing directory by directory, we'd likely have a lot fewer\nproblems.\n\n> I wonder if you let the \"cloud\" services to continuously sync your\n> repository, then go quiescent for a while and then start touching\n> the destination, it would be sufficient, though. The refs with\n> funny \"2\" suffixes and the like are the symptom of two sides\n> simultanously mucking with the same file (e.g \".git/refs/main\") and\n> the \"cloud sync\" could not decide what the right final outcome is,\n> right?\n\nI think this is very risky. Yes, usually the duplicate files are caused\nby competing changes on both sides, but having seen users with this\nproblem before, I'm not sure if we can safely guarantee this is the only\ncase.\n\n> I also wonder if we add a way to transfer reflog entries, that imply\n> the object reachability, say \"git push --with-reflog\", over the\n> wire, it would be sufficient to do everything with Git.\n\nYes, please. I'd love to see this.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"},{"id":"445413","messageId":"nycvar.QRO.7.76.6.2201041427550.7076@tvgsbejvaqbjf.bet","threadId":"56857","inReplyTo":"20211107225525.431138-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 1/3] gitfaq: add documentation on proxies","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2022-01-04T13:40:16Z","receivedAt":"2022-01-04T13:40:41Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi brian,\n\nOn Sun, 7 Nov 2021, brian m. carlson wrote:\n\n> Many corporate environments and local systems have proxies in use. Note\n> the situations in which proxies can be used and how to configure them.\n> At the same time, note what standards a proxy must follow to work with\n> Git. Explicitly call out certain classes that are known to routinely\n> have problems reported various places online, including in the Git for\n\nNot a big issue, but I think there is an \"at\" or \"to\" missing before\n\"various places online\".\n\n> Windows issue tracker and on Stack Overflow, and recommend against the\n> use of such software.\n>\n> Signed-off-by: brian m. carlson \n> ---\n> Documentation/gitfaq.txt | 23 +++++++++++++++++++++++\n> 1 file changed, 23 insertions(+)\n>\n> diff --git a/Documentation/gitfaq.txt b/Documentation/gitfaq.txt\n> index 946691c153..5c21951f7b 100644\n> --- a/Documentation/gitfaq.txt\n> +++ b/Documentation/gitfaq.txt\n> @@ -241,6 +241,29 @@ How do I know if I want to do a fetch or a pull?::\n> \tignore the upstream changes. A pull consists of a fetch followed\n> \timmediately by either a merge or rebase. See linkgit:git-pull[1].\n>\n> +[[proxy]]\n> +Can I use a proxy with Git?::\n> +\tYes, Git supports the use of proxies. Git honors the standard `http_proxy`,\n> +\t`https_proxy`, and `no_proxy` environment variables commonly used on Unix, and\n> +\tit also can be configured with `http.proxy` and similar options for HTTPS (see\n> +\tlinkgit:git-config[1]). The `http.proxy` and related options can be\n> +\tcustomized on a per-URL pattern basis. In addition, Git can in theory\n> +\tfunction normally with transparent proxies that exist on the network.\n> ++\n> +For SSH, Git can support a proxy using `core.gitproxy`. Commonly used tools\n> +include `netcat` and `socat`.\n\nThe first idea I had after reading this is: where are these examples\ndocumented? Certainly not where I expected them, namely at\nhttps://git-scm.com/docs/git-config#Documentation/git-config.txt-coregitProxy\n\nAnd then I got puzzled. Why would `gitproxy` be used for the _SSH_\nprotocol? And I don't think it is used. I think it is only used for\nconnections using the `git://` protocol. I might very easily be wrong, of\ncourse.\n\n> However, they must be configured not to exit when +seeing EOF on\n> standard input, which usually means that `netcat` will require +`-q` and\n> `socat` will require a timeout with something like `-t 10`.\n\nIMHO it would make sense to add a concrete example, or maybe even two\nconcrete examples, one for `netcat` and one for `socat`.\n\n> ++\n> +Note that in all cases, for Git to work properly, the proxy must be completely\n> +transparent. The proxy cannot modify, tamper with, change, or buffer the\n> +connection in any way, or Git will almost certainly fail to work. Note that\n> +many proxies, including many TLS middleboxes, Windows antivirus and firewall\n> +programs other than Windows Defender and Windows Firewall, and filtering proxies\n> +fail to meet this standard, and as a result end up breaking Git. Because of the\n> +many reports of problems, we recommend against the use of these classes of\n> +software and devices.\n> +\n\nThis is good advice.\n\nCiao,\nDscho\n"},{"id":"445414","messageId":"nycvar.QRO.7.76.6.2201041450180.7076@tvgsbejvaqbjf.bet","threadId":"56857","inReplyTo":"CAPig+cTWwmVFggD2UL=Ddd3rc007zRWcRs7nQtEHSS5kgjx4og@mail.gmail.com","subject":"Re: [PATCH v2 0/3] Additional FAQ entries","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2022-01-04T13:53:27Z","receivedAt":"2022-01-04T13:53:54Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Eric,\n\nOn Sun, 7 Nov 2021, Eric Sunshine wrote:\n\n> On Sun, Nov 7, 2021 at 5:55 PM brian m. carlson\n> wrote:\n> > This series introduces some additional Git FAQ entries on various\n> > topics. They are all things I've seen in my professional life or on\n> > Stack Overflow, so I've written documentation.\n> >\n> > Changes from v1:\n> > * Drop the monorepo patch for now; I want to revise it further.\n> > * Reorder the working tree patch to place more warnings up front.\n> > * Mention core.gitproxy and socat.\n> > * Rephrase text in the EOL entry to read correctly and be easier to\n> > understand.\n> > * Improve the commit message for the working tree FAQ entry to make it\n> > clearer that users wish to transfer uncommitted changes.\n>\n> Thanks for re-rolling. FAQ entries are, of course, bikeshedding\n> fodder,\n\nThat is one possible perspective. Another possible perspective is that FAQ\nentries are the first thing users in distress might turn to, so the more\nhelpful they are, the better. Maybe it would make sense to focus on that\na bit more. As in your suggestion to name cloud sync providers by name, to\nmake the FAQ entry eminently more \"findable\". To me, that did not at all\nfeel like pointless bike-shedding, but more like a really valuable\nimprovement that users will appreciate (even if they will be oblivious of\nthe fact that they appreciate it, of course).\n\nCiao,\nDscho\n"},{"id":"445415","messageId":"nycvar.QRO.7.76.6.2201041453540.7076@tvgsbejvaqbjf.bet","threadId":"56857","inReplyTo":"20211107225525.431138-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2 0/3] Additional FAQ entries","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2022-01-04T13:54:52Z","receivedAt":"2022-01-04T13:55:17Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi brian,\n\nOn Sun, 7 Nov 2021, brian m. carlson wrote:\n\n> This series introduces some additional Git FAQ entries on various\n> topics. They are all things I've seen in my professional life or on\n> Stack Overflow, so I've written documentation.\n>\n> I've opted not to include backing up repositories in the syncing patch\n> because I think they're separate topics. We could well end up with an\n> additional FAQ entry on that topic, which is left as an exercise for the\n> reader.\n\nMakes sense.\n\nYou hinted in the thread that you were planning on submitting a v3. I hope\nthat my feedback regarding `core.gitproxy` is still in time for that.\n\nThank you,\nDscho\n"},{"id":"445605","messageId":"YdZMxeOSFQPYBmZY@camp.crustytoothpaste.net","threadId":"56857","inReplyTo":"nycvar.QRO.7.76.6.2201041453540.7076@tvgsbejvaqbjf.bet","subject":"Re: [PATCH v2 0/3] Additional FAQ entries","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2022-01-06T01:58:29Z","receivedAt":"2022-01-06T01:58:44Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2022-01-04 at 13:54:52, Johannes Schindelin wrote:\n> Hi brian,\n> \n> On Sun, 7 Nov 2021, brian m. carlson wrote:\n> \n> > This series introduces some additional Git FAQ entries on various\n> > topics. They are all things I've seen in my professional life or on\n> > Stack Overflow, so I've written documentation.\n> >\n> > I've opted not to include backing up repositories in the syncing patch\n> > because I think they're separate topics. We could well end up with an\n> > additional FAQ entry on that topic, which is left as an exercise for the\n> > reader.\n> \n> Makes sense.\n> \n> You hinted in the thread that you were planning on submitting a v3. I hope\n> that my feedback regarding `core.gitproxy` is still in time for that.\n\nI can definitely include that in v3. I'm hoping I can get to it later\nthis week or during the weekend before my schedule becomes busy again.\n\nI appreciate the thoughtful comments.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"}]}