{"thread":{"id":"52676","subject":"[PATCH v5 0/5] Documentation for common user misconceptions","startedAt":"2020-01-22T03:45:55Z","lastAt":"2020-01-22T19:25:25Z","messageCount":8,"participants":["brian m. carlson","Jeff King","Emily Shaffer"],"isPatch":true,"patchVersion":5,"patchTotal":5},"messages":[{"id":"390220","messageId":"20200122034543.18927-1-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":null,"subject":"[PATCH v5 0/5] Documentation for common user misconceptions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:38Z","receivedAt":"2020-01-22T03:45:55Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"This is v5 of a series improving the documentation to cover common user\nmisconceptions.\n\nChanges from v4:\n* Add a reference to git(1) for environment variables.\n* Remove duplicated text.\n* Add Peff's sign-off.\n\nChanges from v3:\n* Restructure docs around git-commit(1).\n* Improve wording about templating as suggested by Peff.\n* Document ordering between user.*, author.*, and committer.*.\n* Document the environment variables more thoroughly.\n\nChanges from v2:\n* Move author and committer information to git-commit(1) where people\n will look for it.\n* Move guidance on user.name format to git-commit(1) as well and mention\n a shortened form of the advice in the `user.name` description.\n* Use a parenthetical to describe a \"personal name\" without contrasting\n it with a username.\n* Offer a potential solution for people who want to ignore tracked\n files by recommending a templating mechanism.\n* Be slightly more verbose about why memory is wasted with\n http.postBuffer.\n\nChanges from v1:\n* Remove parenthetical which was confusing.\n* Add two more patches.\n\nbrian m. carlson (5):\n doc: move author and committer information to git-commit(1)\n docs: expand on possible and recommended user config options\n doc: provide guidance on user.name format\n doc: dissuade users from trying to ignore tracked files\n docs: mention when increasing http.postBuffer is valuable\n\n Documentation/config/http.txt | 8 ++++++\n Documentation/config/user.txt | 7 +++++-\n Documentation/git-commit-tree.txt | 22 +---------------\n Documentation/git-commit.txt | 40 +++++++++++++++++++++++++++---\n Documentation/git-update-index.txt | 16 ++++++++++++\n Documentation/git.txt | 27 ++++++++++++++++++--\n 6 files changed, 93 insertions(+), 27 deletions(-)\n\nRange-diff against v4:\n1: 0433792871 ! 1: fe2dcea128 doc: move author and committer information to git-commit(1)\n @@ Documentation/config/user.txt: committer.email::\n \tInstruct Git to avoid trying to guess defaults for `user.email`\n \n ## Documentation/git-commit-tree.txt ##\n -@@ Documentation/git-commit-tree.txt: tend to just write the result to the file that is pointed at by\n - `.git/HEAD`, so that we can always see what the last committed\n - state was.\n - \n -+A commit comment is read from stdin. If a changelog\n -+entry is not provided via \"<\" redirection, 'git commit-tree' will just wait\n -+for one to be entered and terminated with ^D.\n -+\n - OPTIONS\n - -------\n - ::\n @@ Documentation/git-commit-tree.txt: OPTIONS\n \tDo not GPG-sign commit, to countermand a `--gpg-sign` option\n \tgiven earlier on the command line.\n2: 8745faf560 = 2: 8d4940efab docs: expand on possible and recommended user config options\n3: 277a151e2c ! 3: a82522e479 doc: provide guidance on user.name format\n @@ Documentation/config/user.txt: committer.email::\n -\tSee linkgit:git-commit[1] for more information.\n ++\n +Note that the `name` forms of these variables conventionally refer to\n -+some form of a personal name.\n -+See linkgit:git-commit[1] for more information on these settings and\n -+the `credential.username` option if you're looking for authentication\n -+credentials instead.\n ++some form of a personal name. See linkgit:git-commit[1] and the\n ++environment variables section of linkgit:git[1] for more information on\n ++these settings and the `credential.username` option if you're looking\n ++for authentication credentials instead.\n \n user.useConfigOnly::\n \tInstruct Git to avoid trying to guess defaults for `user.email`\n4: 6b593861b5 ! 4: 1c95dec93e doc: dissuade users from trying to ignore tracked files\n @@ Commit message\n common case of configuration files, since there are well-known\n approaches used successfully in many environments.\n \n + Signed-off-by: Jeff King \n Signed-off-by: brian m. carlson \n \n ## Documentation/git-update-index.txt ##\n5: 960c80eda3 = 5: 51335b1a49 docs: mention when increasing http.postBuffer is valuable\n"},{"id":"390221","messageId":"20200122034543.18927-3-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"[PATCH v5 2/5] docs: expand on possible and recommended user config options","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:40Z","receivedAt":"2020-01-22T03:45:55Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"In the section on setting author and committer information, we omit the\nauthor.* and committer.* variables, so mention them for completeness.\nIn addition, guide users to the typical case: simply setting user.name\nand user.email, which are recommended if one does not need complex\nconfiguration.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/git-commit.txt | 7 +++++++\n 1 file changed, 7 insertions(+)\n\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 30c30ccd80..7b61c9ba79 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -482,6 +482,13 @@ system user name and the hostname used for outgoing mail (taken\n from `/etc/mailname` and falling back to the fully qualified hostname when\n that file does not exist).\n \n+The `author.name` and `committer.name` and their corresponding email options\n+override `user.name` and `user.email` if set and are overridden themselves by\n+the environment variables.\n+\n+The typical usage is to set just the `user.name` and `user.email` variables;\n+the other options are provided for more complex use cases.\n+\n :git-commit: 1\n include::date-formats.txt[]\n \n"},{"id":"390222","messageId":"20200122034543.18927-2-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"[PATCH v5 1/5] doc: move author and committer information to git-commit(1)","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:39Z","receivedAt":"2020-01-22T03:45:55Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"While at one time it made perfect sense to store information about\nconfiguring author and committer information in the documentation for\ngit commit-tree, in modern Git that operation is seldom used. Most\nusers will use git commit and expect to find comprehensive documentation\nabout its use in the manual page for that command.\n\nConsidering that there is significant confusion about how one is to use\nthe user.name and user.email variables, let's put as much documentation\nas possible into an obvious place where users will be more likely to\nfind it.\n\nIn addition, expand the environment variables section to describe their\nuse more fully. Even though we now describe all of the options there\nand in the configuration settings documentation, preserve the existing\ntext in git-commit.txt so that people can easily reason about the\nordering of the various options they can use. Explain the use of the\nauthor.* and committer.* options as well.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/config/user.txt | 2 +-\n Documentation/git-commit-tree.txt | 22 +---------------------\n Documentation/git-commit.txt | 27 ++++++++++++++++++++++++---\n Documentation/git.txt | 27 +++++++++++++++++++++++++--\n 4 files changed, 51 insertions(+), 27 deletions(-)\n\ndiff --git a/Documentation/config/user.txt b/Documentation/config/user.txt\nindex 0557cbbceb..a1f80e823c 100644\n--- a/Documentation/config/user.txt\n+++ b/Documentation/config/user.txt\n@@ -13,7 +13,7 @@ committer.email::\n \tAlso, all of these can be overridden by the `GIT_AUTHOR_NAME`,\n \t`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,\n \t`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.\n-\tSee linkgit:git-commit-tree[1] for more information.\n+\tSee linkgit:git-commit[1] for more information.\n \n user.useConfigOnly::\n \tInstruct Git to avoid trying to guess defaults for `user.email`\ndiff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\nindex 4b90b9c12a..ec15ee8d6f 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -69,7 +69,6 @@ OPTIONS\n \tDo not GPG-sign commit, to countermand a `--gpg-sign` option\n \tgiven earlier on the command line.\n \n-\n Commit Information\n ------------------\n \n@@ -79,26 +78,6 @@ A commit encapsulates:\n - author name, email and date\n - committer name and email and the commit time.\n \n-While parent object ids are provided on the command line, author and\n-committer information is taken from the following environment variables,\n-if set:\n-\n-\tGIT_AUTHOR_NAME\n-\tGIT_AUTHOR_EMAIL\n-\tGIT_AUTHOR_DATE\n-\tGIT_COMMITTER_NAME\n-\tGIT_COMMITTER_EMAIL\n-\tGIT_COMMITTER_DATE\n-\n-(nb \"<\", \">\" and \"\\n\"s are stripped)\n-\n-In case (some of) these environment variables are not set, the information\n-is taken from the configuration items user.name and user.email, or, if not\n-present, the environment variable EMAIL, or, if that is not set,\n-system user name and the hostname used for outgoing mail (taken\n-from `/etc/mailname` and falling back to the fully qualified hostname when\n-that file does not exist).\n-\n A commit comment is read from stdin. If a changelog\n entry is not provided via \"<\" redirection, 'git commit-tree' will just wait\n for one to be entered and terminated with ^D.\n@@ -117,6 +96,7 @@ FILES\n SEE ALSO\n --------\n linkgit:git-write-tree[1]\n+linkgit:git-commit[1]\n \n GIT\n ---\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex ced5a9beab..30c30ccd80 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -367,9 +367,6 @@ changes to tracked files.\n +\n For more details, see the 'pathspec' entry in linkgit:gitglossary[7].\n \n-:git-commit: 1\n-include::date-formats.txt[]\n-\n EXAMPLES\n --------\n When recording your own work, the contents of modified files in\n@@ -463,6 +460,30 @@ alter the order the changes are committed, because the merge\n should be recorded as a single commit. In fact, the command\n refuses to run when given pathnames (but see `-i` option).\n \n+COMMIT INFORMATION\n+------------------\n+\n+Author and committer information is taken from the following environment\n+variables, if set:\n+\n+\tGIT_AUTHOR_NAME\n+\tGIT_AUTHOR_EMAIL\n+\tGIT_AUTHOR_DATE\n+\tGIT_COMMITTER_NAME\n+\tGIT_COMMITTER_EMAIL\n+\tGIT_COMMITTER_DATE\n+\n+(nb \"<\", \">\" and \"\\n\"s are stripped)\n+\n+In case (some of) these environment variables are not set, the information\n+is taken from the configuration items `user.name` and `user.email`, or, if not\n+present, the environment variable EMAIL, or, if that is not set,\n+system user name and the hostname used for outgoing mail (taken\n+from `/etc/mailname` and falling back to the fully qualified hostname when\n+that file does not exist).\n+\n+:git-commit: 1\n+include::date-formats.txt[]\n \n DISCUSSION\n ----------\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex b1597ac002..0093c647bf 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -482,13 +482,36 @@ double-quotes and respecting backslash escapes. E.g., the value\n Git Commits\n ~~~~~~~~~~~\n `GIT_AUTHOR_NAME`::\n+\tThe human-readable name used in the author identity when creating commit or\n+\ttag objects, or when writing reflogs. Overrides the `user.name` and\n+\t`author.name` configuration settings.\n+\n `GIT_AUTHOR_EMAIL`::\n+\tThe email address used in the author identity when creating commit or\n+\ttag objects, or when writing reflogs. Overrides the `user.email` and\n+\t`author.email` configuration settings.\n+\n `GIT_AUTHOR_DATE`::\n+\tThe date used for the author identity when creating commit or tag objects, or\n+\twhen writing reflogs. See linkgit:git-commit[1] for valid formats.\n+\n `GIT_COMMITTER_NAME`::\n+\tThe human-readable name used in the committer identity when creating commit or\n+\ttag objects, or when writing reflogs. Overrides the `user.name` and\n+\t`committer.name` configuration settings.\n+\n `GIT_COMMITTER_EMAIL`::\n+\tThe email address used in the author identity when creating commit or\n+\ttag objects, or when writing reflogs. Overrides the `user.email` and\n+\t`committer.email` configuration settings.\n+\n `GIT_COMMITTER_DATE`::\n-'EMAIL'::\n-\tsee linkgit:git-commit-tree[1]\n+\tThe date used for the committer identity when creating commit or tag objects, or\n+\twhen writing reflogs. See linkgit:git-commit[1] for valid formats.\n+\n+`EMAIL`::\n+\tThe email address used in the author and committer identities if no other\n+\trelevant environment variable or configuration setting has been set.\n \n Git Diffs\n ~~~~~~~~~\n"},{"id":"390223","messageId":"20200122034543.18927-4-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"[PATCH v5 3/5] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:41Z","receivedAt":"2020-01-22T03:46:14Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"It's a frequent misconception that the user.name variable controls\nauthentication in some way, and as a result, beginning users frequently\nattempt to change it when they're having authentication troubles.\nDocument that the convention is that this variable represents some form\nof a human's personal name, although that is not required. In addition,\naddress concerns about whether Unicode is supported.\n\nUse the term \"personal name\" as this is likely to draw the intended\ncontrast, be applicable across cultures which may have different naming\nconventions, and be easily understandable to people who do not speak\nEnglish as their first language. Indicate that \"some form\" is\nconventionally used, as people may use a nickname or preferred name\ninstead of a full legal name.\n\nPoint users who may be confused about authentication to an appropriate\nconfiguration option instead. Provide a shortened form of this\ninformation in the configuration option description.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/config/user.txt | 7 ++++++-\n Documentation/git-commit.txt | 6 ++++++\n 2 files changed, 12 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config/user.txt b/Documentation/config/user.txt\nindex a1f80e823c..59aec7c3ae 100644\n--- a/Documentation/config/user.txt\n+++ b/Documentation/config/user.txt\n@@ -13,7 +13,12 @@ committer.email::\n \tAlso, all of these can be overridden by the `GIT_AUTHOR_NAME`,\n \t`GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`,\n \t`GIT_COMMITTER_EMAIL` and `EMAIL` environment variables.\n-\tSee linkgit:git-commit[1] for more information.\n++\n+Note that the `name` forms of these variables conventionally refer to\n+some form of a personal name. See linkgit:git-commit[1] and the\n+environment variables section of linkgit:git[1] for more information on\n+these settings and the `credential.username` option if you're looking\n+for authentication credentials instead.\n \n user.useConfigOnly::\n \tInstruct Git to avoid trying to guess defaults for `user.email`\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 7b61c9ba79..13f653989f 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -475,6 +475,12 @@ variables, if set:\n \n (nb \"<\", \">\" and \"\\n\"s are stripped)\n \n+The author and committer names are by convention some form of a personal name\n+(that is, the name by which other humans refer to you), although Git does not\n+enforce or require any particular form. Arbitrary Unicode may be used, subject\n+to the constraints listed above. This name has no effect on authentication; for\n+that, see the `credential.username` variable in linkgit:git-config[1].\n+\n In case (some of) these environment variables are not set, the information\n is taken from the configuration items `user.name` and `user.email`, or, if not\n present, the environment variable EMAIL, or, if that is not set,\n"},{"id":"390224","messageId":"20200122034543.18927-6-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"[PATCH v5 5/5] docs: mention when increasing http.postBuffer is valuable","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:43Z","receivedAt":"2020-01-22T03:46:15Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"Users in a wide variety of situations find themselves with HTTP push\nproblems. Oftentimes these issues are due to antivirus software,\nfiltering proxies, or other man-in-the-middle situations; other times,\nthey are due to simple unreliability of the network.\n\nHowever, a common solution to HTTP push problems found online is to\nincrease http.postBuffer. This works for none of the aforementioned\nsituations and is only useful in a small, highly restricted number of\ncases: essentially, when the connection does not properly support\nHTTP/1.1.\n\nDocument when raising this value is appropriate and what it actually\ndoes, and discourage people from using it as a general solution for push\nproblems, since it is not effective there.\n\nSigned-off-by: brian m. carlson \n---\n Documentation/config/http.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/config/http.txt b/Documentation/config/http.txt\nindex 5a32f5b0a5..3d1db91f05 100644\n--- a/Documentation/config/http.txt\n+++ b/Documentation/config/http.txt\n@@ -199,6 +199,14 @@ http.postBuffer::\n \tTransfer-Encoding: chunked is used to avoid creating a\n \tmassive pack file locally. Default is 1 MiB, which is\n \tsufficient for most requests.\n++\n+Note that raising this limit is only effective for disabling chunked\n+transfer encoding and therefore should be used only where the remote\n+server or a proxy only supports HTTP/1.0 or is noncompliant with the\n+HTTP standard. Raising this is not, in general, an effective solution\n+for most push problems, but can increase memory consumption\n+significantly since the entire buffer is allocated even for small\n+pushes.\n \n http.lowSpeedLimit, http.lowSpeedTime::\n \tIf the HTTP transfer speed is less than 'http.lowSpeedLimit'\n"},{"id":"390225","messageId":"20200122034543.18927-5-sandals@crustytoothpaste.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"[PATCH v5 4/5] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-22T03:45:42Z","receivedAt":"2020-01-22T03:46:15Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"It is quite common for users to want to ignore the changes to a file\nthat Git tracks. Common scenarios for this case are IDE settings and\nconfiguration files, which should generally not be tracked and possibly\ngenerated from tracked files using a templating mechanism.\n\nHowever, users learn about the assume-unchanged and skip-worktree bits\nand try to use them to do this anyway. This is problematic, because\nwhen these bits are set, many operations behave as the user expects, but\nthey usually do not help when git checkout needs to replace a file.\n\nThere is no sensible behavior in this case, because sometimes the data\nis precious, such as certain configuration files, and sometimes it is\nirrelevant data that the user would be happy to discard.\n\nSince this is not a supported configuration and users are prone to\nmisuse the existing features for unintended purposes, causing general\nsadness and confusion, let's document the existing behavior and the\npitfalls in the documentation for git update-index so that users know\nthey should explore alternate solutions.\n\nIn addition, let's provide a recommended solution to dealing with the\ncommon case of configuration files, since there are well-known\napproaches used successfully in many environments.\n\nSigned-off-by: Jeff King \nSigned-off-by: brian m. carlson \n---\n Documentation/git-update-index.txt | 16 ++++++++++++++++\n 1 file changed, 16 insertions(+)\n\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex c7a6271daf..1489cb09a0 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -549,6 +549,22 @@ The untracked cache extension can be enabled by the\n `core.untrackedCache` configuration variable (see\n linkgit:git-config[1]).\n \n+NOTES\n+-----\n+\n+Users often try to use the assume-unchanged and skip-worktree bits\n+to tell Git to ignore changes to files that are tracked. This does not\n+work as expected, since Git may still check working tree files against\n+the index when performing certain operations. In general, Git does not\n+provide a way to ignore changes to tracked files, so alternate solutions\n+are recommended.\n+\n+For example, if the file you want to change is some sort of config file,\n+the repository can include a sample config file that can then be copied\n+into the ignored name and modified. The repository can even include a\n+script to treat the sample file as a template, modifying and copying it\n+automatically.\n+\n SEE ALSO\n --------\n linkgit:git-config[1],\n"},{"id":"390226","messageId":"20200122035247.GB18266@coredump.intra.peff.net","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v5 0/5] Documentation for common user misconceptions","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-01-22T03:52:47Z","receivedAt":"2020-01-22T03:52:49Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Jan 22, 2020 at 03:45:38AM +0000, brian m. carlson wrote:\n\n> This is v5 of a series improving the documentation to cover common user\n> misconceptions.\n> \n> Changes from v4:\n> * Add a reference to git(1) for environment variables.\n> * Remove duplicated text.\n> * Add Peff's sign-off.\n\nThanks, just looking at the interdiff I think this addresses all of my\ncomments.\n\n-Peff\n"},{"id":"390239","messageId":"20200122192518.GO181522@google.com","threadId":"52676","inReplyTo":"20200122034543.18927-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v5 0/5] Documentation for common user misconceptions","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2020-01-22T19:25:18Z","receivedAt":"2020-01-22T19:25:25Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Wed, Jan 22, 2020 at 03:45:38AM +0000, brian m. carlson wrote:\n> This is v5 of a series improving the documentation to cover common user\n> misconceptions.\n\nThanks - it makes me happy to see these kinds of clarifications come\nthrough.\n\nReviewed-by: Emily Shaffer \n"}]}