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

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

[brian m. carlson]

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(+)

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

[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.

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(+)

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,

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

[Jeff King]

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?

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> 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").

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

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 2285 bytes --]

On 2019-10-17 at 05:40:52, Jeff King wrote:
> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 868 bytes --]

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

[Jeff King]

On Thu, Oct 17, 2019 at 10:20:38PM +0000, brian m. carlson wrote:

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

> 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

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

[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.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-update-index.txt | 10 ++++++++++
 1 file changed, 10 insertions(+)

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],

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

[Jeff King]

On Thu, Oct 17, 2019 at 12:53:29AM +0000, brian m. carlson wrote:

> 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

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

[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.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/http.txt | 7 +++++++
 1 file changed, 7 insertions(+)

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'

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

[Jeff King]

On Thu, Oct 17, 2019 at 12:53:30AM +0000, brian m. carlson wrote:

> 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