Skip to contentSkip to conversation

Documentation for common user misconceptions

PATCH Superseded brian m. carlson 3 participants 10 messages Oct 17, 2019 – Oct 18, 2019 Documentation

v2 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v2 cover 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(+)
#1 lore raw

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.

---
 Documentation/git-commit-tree.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/git-commit-tree.txt +6 -0
index 4b90b9c12a..c794843634 100644
@@ -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,
#2 lore raw

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

Quoted 14 lines · brian m. carlson

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.

Quoted 2 lines

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

I think this is a good distinction to draw, but...

Quoted 2 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?

-Peff

#3 lore raw

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

Quoted 8 lines · Jeff King

I think this is a good distinction to draw, but...

Quoted 2 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?

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

#4 lore raw

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

In reply to Jeff King
Quoted 19 lines · Jeff King
Quoted 14 lines · brian m. carlson

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.

Quoted 2 lines

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

Quoted 8 lines

I think this is a good distinction to draw, but...

Quoted 2 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.

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.

Signature · 2 lines
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204
#5 lore raw

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

Quoted 7 lines · brian m. carlson
Quoted 6 lines
Quoted 2 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?

Quoted 5 lines

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.

Quoted 5 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

#6 lore raw

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

In reply to brian m. carlson

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.

---
 Documentation/git-update-index.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/git-update-index.txt +10 -0
index 1c4d146a41..502e06abc0 100644
@@ -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],
#7 lore raw

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

Quoted 9 lines · brian m. carlson

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

#8 lore raw

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

In reply to brian m. carlson

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.

---
 Documentation/config/http.txt | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/config/http.txt +7 -0
index 5a32f5b0a5..ba7198846d 100644
@@ -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'
#9 lore raw

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

Quoted 11 lines · brian m. carlson

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.

Quoted 3 lines

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