From 1b13e9032f039c8cdb1994dd092ff2ed32af5cf5 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Wed, 22 Jan 2020 03:45:42 +0000 Subject: doc: dissuade users from trying to ignore tracked files It is quite common for users to want to ignore the changes to a file that Git tracks. Common scenarios for this case are IDE settings and configuration files, which should generally not be tracked and possibly generated from tracked files using a templating mechanism. However, users learn about the assume-unchanged and skip-worktree bits and try to use them to do this anyway. This is problematic, because when these bits are set, many operations behave as the user expects, but they usually do not help when git checkout needs to replace a file. There is no sensible behavior in this case, because sometimes the data is precious, such as certain configuration files, and sometimes it is irrelevant data that the user would be happy to discard. Since this is not a supported configuration and users are prone to misuse the existing features for unintended purposes, causing general sadness and confusion, let's document the existing behavior and the pitfalls in the documentation for git update-index so that users know they should explore alternate solutions. In addition, let's provide a recommended solution to dealing with the common case of configuration files, since there are well-known approaches used successfully in many environments. Signed-off-by: Jeff King Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index c7a6271..1489cb0 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -549,6 +549,22 @@ The untracked cache extension can be enabled by the `core.untrackedCache` configuration variable (see linkgit:git-config[1]). +NOTES +----- + +Users often try to use the assume-unchanged and skip-worktree bits +to tell Git to ignore changes to files that are tracked. This does not +work as expected, since Git may still check working tree files against +the index when performing certain operations. In general, Git does not +provide a way to ignore changes to tracked files, so alternate solutions +are recommended. + +For example, if the file you want to change is some sort of config file, +the repository can include a sample config file that can then be copied +into the ignored name and modified. The repository can even include a +script to treat the sample file as a template, modifying and copying it +automatically. + SEE ALSO -------- linkgit:git-config[1], -- cgit v0.10.2-6-g49f6 From 7a2dc95cbc25b4b82cff35931f69f8a5aafeb878 Mon Sep 17 00:00:00 2001 From: "brian m. carlson" Date: Wed, 22 Jan 2020 03:45:43 +0000 Subject: docs: mention when increasing http.postBuffer is valuable Users in a wide variety of situations find themselves with HTTP push problems. Oftentimes these issues are due to antivirus software, filtering proxies, or other man-in-the-middle situations; other times, they are due to simple unreliability of the network. However, a common solution to HTTP push problems found online is to increase http.postBuffer. This works for none of the aforementioned situations and is only useful in a small, highly restricted number of cases: essentially, when the connection does not properly support HTTP/1.1. Document when raising this value is appropriate and what it actually does, and discourage people from using it as a general solution for push problems, since it is not effective there. Signed-off-by: brian m. carlson Signed-off-by: Junio C Hamano diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt index 5a32f5b..3d1db91 100644 --- a/Documentation/config/http.txt +++ b/Documentation/config/http.txt @@ -199,6 +199,14 @@ http.postBuffer:: Transfer-Encoding: chunked is used to avoid creating a massive pack file locally. Default is 1 MiB, which is sufficient for most requests. ++ +Note that raising this limit is only effective for disabling chunked +transfer encoding and therefore should be used only where the remote +server or a proxy only supports HTTP/1.0 or is noncompliant with the +HTTP standard. Raising this is not, in general, an effective solution +for most push problems, but can increase memory consumption +significantly since the entire buffer is allocated even for small +pushes. http.lowSpeedLimit, http.lowSpeedTime:: If the HTTP transfer speed is less than 'http.lowSpeedLimit' -- cgit v0.10.2-6-g49f6