threads / patch / 52053

v2, 3 partsdocs: mention when increasing http.postBuffer is valuable

Subject: [PATCH v2 3/3] docs: mention when increasing http.postBuffer is valuable

## tl;dr

10 messages between Oct 17, 2019 and Oct 18, 2019. Diffs are folded; open one to read it.

replies: 9people: 3as markdown or json

brian m. carlson· Oct 17, 2019, 00:53 UTC · lore

[PATCH v2 0/3] Documentation for common user misconceptions

This series includes three patches that update the documentation to address common user misconceptions.

The first patch has seen the list before, which is why this is now v2. It addresses the attempt to use "user.name" as a username for $GIT_HOSTING_SERVICE instead of a person's personal name.

The second patch is new, and addresses a common desire (as seen on Stack Overflow) to ignore changes to tracked files. If folks want, I can add a paragraph to expand on the common use cases (IDE configuration and config files) and offer general suggestions for them; if not, we can leave the patch as it stands.

The final patch, also new, addresses a common source of bad advice in response to any push problem: raise http.postBuffer. The patch indicates why this is almost never an effective solution, so explain what the option really does and that it is not a panacea.

We probably should have a document such as a FAQ that addresses these and other common issues, both to make Git more approachable and less scary for newcomers, and provide accurate information for situations like these. I've started on some drafts of such a FAQ, but have gotten side-tracked with other things and haven't made much progress.

In the mean time, it's my hope that by providing documentation on these issues, we can point people to it and encourage people to solutions that solve their problems instead of having them receive incorrect information which is not effective.

Changes from v1:
* Remove parenthetical which was confusing.
* Add two more patches.
brian m. carlson (3):
  doc: provide guidance on user.name format
  doc: dissuade users from trying to ignore tracked files
  docs: mention when increasing http.postBuffer is valuable
 Documentation/config/http.txt      |  7 +++++++
 Documentation/git-commit-tree.txt  |  6 ++++++
 Documentation/git-update-index.txt | 10 ++++++++++
 3 files changed, 23 insertions(+)
brian m. carlson· Oct 17, 2019, 00:53 UTC · re: brian m. carlson · lore

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 <sandals@crustytoothpaste.net>
---
 Documentation/config/http.txt | 7 +++++++
 1 file changed, 7 insertions(+)
Show changes to Documentation/config/http.txt +7 −0
diff --git a/Documentation/config/http.txt b/Documentation/config/http.txt
index 5a32f5b0a5..ba7198846d 100644
--- a/Documentation/config/http.txt
+++ b/Documentation/config/http.txt
@@ -199,6 +199,13 @@ 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.
 
 http.lowSpeedLimit, http.lowSpeedTime::
 	If the HTTP transfer speed is less than 'http.lowSpeedLimit'
Jeff King· Oct 17, 2019, 05:52 UTC · re: brian m. carlson · lore

Re: [PATCH v2 3/3] docs: mention when increasing http.postBuffer is valuable

On Thu, Oct 17, 2019 at 12:53:30AM +0000, brian m. carlson wrote:
Show 14 quoted lines
> 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.

Yeah, I've run into some voodoo advice about this config option before. I think your advice neatly explains the situation.

-Peff
brian m. carlson· Oct 17, 2019, 00:53 UTC · re: brian m. carlson · lore

[PATCH v2 2/3] 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.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-update-index.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)
Show changes to Documentation/git-update-index.txt +10 −0
diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index 1c4d146a41..502e06abc0 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -543,6 +543,16 @@ 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.
+
 SEE ALSO
 --------
 linkgit:git-config[1],
Jeff King· Oct 17, 2019, 05:44 UTC · re: brian m. carlson · lore

Re: [PATCH v2 2/3] doc: dissuade users from trying to ignore tracked files

On Thu, Oct 17, 2019 at 12:53:29AM +0000, brian m. carlson wrote:
Show 9 quoted lines
> 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.

I think this is an improvement. It would be nice if we had some specific alternatives to point them to. But as you note, Git doesn't really have a good solution for this built-in. And I don't know offhand of a complete one that we could recommend. So this is probably the best we can do for now.

-Peff
brian m. carlson· Oct 17, 2019, 00:53 UTC · re: brian m. carlson · lore

[PATCH v2 1/3] doc: provide guidance on user.name format

It's a frequent misconception that the user.name variable controls authentication in some way, and as a result, beginning users frequently attempt to change it when they're having authentication troubles. Document that the convention is that this variable represents some form of a human's personal name, although that is not required. In addition, address concerns about whether Unicode is supported.

Use the term "personal name" as this is likely to draw the intended contrast, be applicable across cultures which may have different naming conventions, and be easily understandable to people who do not speak English as their first language. Indicate that "some form" is conventionally used, as people may use a nickname or preferred name instead of a full legal name.

Point users who may be confused about authentication to an appropriate configuration option instead.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-commit-tree.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Show changes to Documentation/git-commit-tree.txt +6 −0
diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt
index 4b90b9c12a..c794843634 100644
--- a/Documentation/git-commit-tree.txt
+++ b/Documentation/git-commit-tree.txt
@@ -92,6 +92,12 @@ if set:
 
 (nb "<", ">" and "\n"s are stripped)
 
+The author and committer names are by convention some form of a personal name,
+although Git does not enforce or require any particular form. Arbitrary Unicode
+may be used, subject to the constraints listed above. This name has no effect on
+authentication; for that, see the `credential.username` variable in
+linkgit::git-config[1].
+
 In case (some of) these environment variables are not set, the information
 is taken from the configuration items user.name and user.email, or, if not
 present, the environment variable EMAIL, or, if that is not set,
Jeff King· Oct 17, 2019, 05:40 UTC · re: brian m. carlson · lore

Re: [PATCH v2 1/3] doc: provide guidance on user.name format

On Thu, Oct 17, 2019 at 12:53:28AM +0000, brian m. carlson wrote:
Show 16 quoted lines
> It's a frequent misconception that the user.name variable controls
> authentication in some way, and as a result, beginning users frequently
> attempt to change it when they're having authentication troubles.
> Document that the convention is that this variable represents some form
> of a human's personal name, although that is not required.  In addition,
> address concerns about whether Unicode is supported.
> 
> Use the term "personal name" as this is likely to draw the intended
> contrast, be applicable across cultures which may have different naming
> conventions, and be easily understandable to people who do not speak
> English as their first language.  Indicate that "some form" is
> conventionally used, as people may use a nickname or preferred name
> instead of a full legal name.
> 
> Point users who may be confused about authentication to an appropriate
> configuration option instead.
I think this is a good distinction to draw, but...
>  Documentation/git-commit-tree.txt | 6 ++++++
>  1 file changed, 6 insertions(+)

...I was surprised to see it here, where I think most users wouldn't find it. Would it make sense in git-commit(1), or in the description of the user.name config?

-Peff
Junio C Hamano· Oct 17, 2019, 07:39 UTC · re: Jeff King · lore

Re: [PATCH v2 1/3] doc: provide guidance on user.name format

Jeff King <peff@peff.net> writes:
Show 8 quoted lines
> I think this is a good distinction to draw, but...
>
>>  Documentation/git-commit-tree.txt | 6 ++++++
>>  1 file changed, 6 insertions(+)
>
> ...I was surprised to see it here, where I think most users wouldn't
> find it. Would it make sense in git-commit(1), or in the description of
> the user.name config?

Yeah, I had the same reaction as you had, both positive and negative (eh, rather "surprised").

brian m. carlson· Oct 17, 2019, 22:20 UTC · re: Jeff King · lore

Re: [PATCH v2 1/3] doc: provide guidance on user.name format

On 2019-10-17 at 05:40:52, Jeff King wrote:
Show 27 quoted lines
> On Thu, Oct 17, 2019 at 12:53:28AM +0000, brian m. carlson wrote:
> 
> > It's a frequent misconception that the user.name variable controls
> > authentication in some way, and as a result, beginning users frequently
> > attempt to change it when they're having authentication troubles.
> > Document that the convention is that this variable represents some form
> > of a human's personal name, although that is not required.  In addition,
> > address concerns about whether Unicode is supported.
> > 
> > Use the term "personal name" as this is likely to draw the intended
> > contrast, be applicable across cultures which may have different naming
> > conventions, and be easily understandable to people who do not speak
> > English as their first language.  Indicate that "some form" is
> > conventionally used, as people may use a nickname or preferred name
> > instead of a full legal name.
> > 
> > Point users who may be confused about authentication to an appropriate
> > configuration option instead.
> 
> I think this is a good distinction to draw, but...
> 
> >  Documentation/git-commit-tree.txt | 6 ++++++
> >  1 file changed, 6 insertions(+)
> 
> ...I was surprised to see it here, where I think most users wouldn't
> find it. Would it make sense in git-commit(1), or in the description of
> the user.name config?

So the user.name config description points to git-commit-tree(1), which describes these in detail, which is why I put it there. I agree that it's not a super discoverable place, since I don't know anyone that actually uses git commit-tree these days. git-commit(1) doesn't describe these options at all.

There are, of course, options. I can add this text into the `user.name` option in git-config(5) nevertheless, which will likely be more discoverable, but it will split the documentation on those into two separate locations. Or we can leave it in git-commit-tree(1) anyway to keep it together.

Since you and Junio think this is an odd place (and I agree), I think it's fine to separate the text out, and I'll reroll with that change unless someone speaks up strongly against it.

-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204
Jeff King· Oct 18, 2019, 05:37 UTC · re: brian m. carlson · lore

Re: [PATCH v2 1/3] doc: provide guidance on user.name format

On Thu, Oct 17, 2019 at 10:20:38PM +0000, brian m. carlson wrote:
Show 12 quoted lines
> > >  Documentation/git-commit-tree.txt | 6 ++++++
> > >  1 file changed, 6 insertions(+)
> > 
> > ...I was surprised to see it here, where I think most users wouldn't
> > find it. Would it make sense in git-commit(1), or in the description of
> > the user.name config?
> 
> So the user.name config description points to git-commit-tree(1), which
> describes these in detail, which is why I put it there.  I agree that
> it's not a super discoverable place, since I don't know anyone that
> actually uses git commit-tree these days.  git-commit(1) doesn't
> describe these options at all.

Hmm, yeah. It's a little funny to point users at git-commit-tree, I think. Some of that documentation may go better in git-commit. But resolving that may be more than you want to bite off right now.

Show 5 quoted lines
> There are, of course, options.  I can add this text into the `user.name`
> option in git-config(5) nevertheless, which will likely be more
> discoverable, but it will split the documentation on those into two
> separate locations.  Or we can leave it in git-commit-tree(1) anyway to
> keep it together.

I like the idea of mentioning something about it in user.name, even if it's more brief ("Note that this doesn't impact the username used for network authentication; see credential.username" or something).

-Peff

← back to recent threads