{"thread":{"id":"52668","subject":"[PATCH v4 0/6] Documentation for common user misconceptions","startedAt":"2020-01-20T17:33:57Z","lastAt":"2020-01-21T22:35:48Z","messageCount":13,"participants":["brian m. carlson","Jeff King","Junio C Hamano"],"isPatch":true,"patchVersion":4,"patchTotal":6},"messages":[{"id":"390111","messageId":"20200120173343.4102954-1-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":null,"subject":"[PATCH v4 0/6] Documentation for common user misconceptions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:38Z","receivedAt":"2020-01-20T17:33:57Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"This is v4 of a series improving the documentation to cover common user\nmisconceptions.\n\nI did opt to keep the big commit information section because I think it\nprovides value when documenting the ordering of the variables.\nOtherwise, it becomes confusing to advanced users which options control\nwhat and in what order.\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  | 26 ++++---------------\n Documentation/git-commit.txt       | 40 +++++++++++++++++++++++++++---\n Documentation/git-update-index.txt | 16 ++++++++++++\n Documentation/git.txt              | 27 ++++++++++++++++++--\n 6 files changed, 97 insertions(+), 27 deletions(-)\n\n"},{"id":"390112","messageId":"20200120173343.4102954-3-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"[PATCH v4 2/5] docs: expand on possible and recommended user config options","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:40Z","receivedAt":"2020-01-20T17:33:58Z","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 <sandals@crustytoothpaste.net>\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":"390113","messageId":"20200120173343.4102954-5-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"[PATCH v4 4/5] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:42Z","receivedAt":"2020-01-20T17:34:00Z","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: brian m. carlson <sandals@crustytoothpaste.net>\n---\n\nPeff, since I've adopted a significant portion of what you've said here,\nit's probably worth getting your sign-off on this patch.\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":"390114","messageId":"20200120173343.4102954-2-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"[PATCH v4 1/5] doc: move author and committer information to git-commit(1)","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:39Z","receivedAt":"2020-01-20T17:34:01Z","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 <sandals@crustytoothpaste.net>\n---\n Documentation/config/user.txt     |  2 +-\n Documentation/git-commit-tree.txt | 26 +++++---------------------\n Documentation/git-commit.txt      | 27 ++++++++++++++++++++++++---\n Documentation/git.txt             | 27 +++++++++++++++++++++++++--\n 4 files changed, 55 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..adc2e0d4b7 100644\n--- a/Documentation/git-commit-tree.txt\n+++ b/Documentation/git-commit-tree.txt\n@@ -42,6 +42,10 @@ 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 <tree>::\n@@ -69,7 +73,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 +82,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 +100,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":"390115","messageId":"20200120173343.4102954-6-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"[PATCH v4 5/5] docs: mention when increasing http.postBuffer is valuable","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:43Z","receivedAt":"2020-01-20T17:34:02Z","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 <sandals@crustytoothpaste.net>\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":"390116","messageId":"20200120173343.4102954-4-sandals@crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"[PATCH v4 3/5] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T17:33:41Z","receivedAt":"2020-01-20T17:34:03Z","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 <sandals@crustytoothpaste.net>\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..f0edb06329 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.\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 \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":"390117","messageId":"20200120175210.GA3989@coredump.intra.peff.net","threadId":"52668","inReplyTo":"20200120173343.4102954-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v4 1/5] doc: move author and committer information to git-commit(1)","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-01-20T17:52:10Z","receivedAt":"2020-01-20T17:52:13Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jan 20, 2020 at 05:33:39PM +0000, brian m. carlson wrote:\n\n> diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> index 4b90b9c12a..adc2e0d4b7 100644\n> --- a/Documentation/git-commit-tree.txt\n> +++ b/Documentation/git-commit-tree.txt\n> @@ -42,6 +42,10 @@ 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>  <tree>::\n\nThis text got moved up, which kind of make sense to me, but...\n\n> @@ -79,26 +82,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\nit stayed here, so now it's duplicated. Should the old one be dropped?\nOr is moving the new text a leftover mistake from rebasing (IIRC, in\nyour original you dropped this whole \"here's how commits work\" section).\n\nOther than that, the patch looks good to me.\n\n-Peff\n"},{"id":"390118","messageId":"20200120175440.GB3989@coredump.intra.peff.net","threadId":"52668","inReplyTo":"20200120173343.4102954-5-sandals@crustytoothpaste.net","subject":"Re: [PATCH v4 4/5] doc: dissuade users from trying to ignore tracked files","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-01-20T17:54:40Z","receivedAt":"2020-01-20T17:54:43Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jan 20, 2020 at 05:33:42PM +0000, brian m. carlson wrote:\n\n> Peff, since I've adopted a significant portion of what you've said here,\n> it's probably worth getting your sign-off on this patch.\n\nSure thing:\n\n  Signed-off-by: Jeff King <peff@peff.net>\n\nAnd the patch itself looks good to me.\n\n-Peff\n"},{"id":"390119","messageId":"20200120175527.GC3989@coredump.intra.peff.net","threadId":"52668","inReplyTo":"20200120173343.4102954-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v4 0/6] Documentation for common user misconceptions","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2020-01-20T17:55:27Z","receivedAt":"2020-01-20T17:55:29Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Jan 20, 2020 at 05:33:38PM +0000, brian m. carlson wrote:\n\n> This is v4 of a series improving the documentation to cover common user\n> misconceptions.\n\nWith the exception of the minor issue I pointed out in patch 1, these\nall look good to me.\n\n-Peff\n"},{"id":"390122","messageId":"20200120192204.GD6570@camp.crustytoothpaste.net","threadId":"52668","inReplyTo":"20200120175210.GA3989@coredump.intra.peff.net","subject":"Re: [PATCH v4 1/5] doc: move author and committer information to git-commit(1)","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-20T19:22:04Z","receivedAt":"2020-01-20T19:22:12Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-01-20 at 17:52:10, Jeff King wrote:\n> On Mon, Jan 20, 2020 at 05:33:39PM +0000, brian m. carlson wrote:\n> \n> > diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> > index 4b90b9c12a..adc2e0d4b7 100644\n> > --- a/Documentation/git-commit-tree.txt\n> > +++ b/Documentation/git-commit-tree.txt\n> > @@ -42,6 +42,10 @@ 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> >  <tree>::\n> \n> This text got moved up, which kind of make sense to me, but...\n> \n> it stayed here, so now it's duplicated. Should the old one be dropped?\n> Or is moving the new text a leftover mistake from rebasing (IIRC, in\n> your original you dropped this whole \"here's how commits work\" section).\n> \n> Other than that, the patch looks good to me.\n\nThanks for pointing this out.  I'll fix it and if nobody else has\ncomments today, send out a v5 later this week, probably tomorrow.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"390209","messageId":"xmqqd0bc8n4k.fsf@gitster-ct.c.googlers.com","threadId":"52668","inReplyTo":"20200120173343.4102954-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v4 1/5] doc: move author and committer information to git-commit(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-21T22:23:39Z","receivedAt":"2020-01-21T22:23:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt\n> index 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\nMakes sense---it is consistent with the goal of making the\ndocumentation of \"git commit\" Porcelain the central place for\nauthorship and committer information.\n\n> diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> index 4b90b9c12a..adc2e0d4b7 100644\n> --- a/Documentation/git-commit-tree.txt\n> +++ b/Documentation/git-commit-tree.txt\n> @@ -42,6 +42,10 @@ 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\nThis is copied from the end of the \"commit information\" section,\nwithout the original getting removed (see the post-context of the\nhunk that begins at l.79/l.82).  Intended?\n\nI haven't seen anybody use the phrase \"commit comment\" in the\nreviews on this list for long time; the phrase somehow feels\noutdated.  The pretty formats section in \"git log --help\" calls\nthis \"commit message\".  \"log message\" may also be more common.\n\n> @@ -69,7 +73,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 +82,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> -...\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 +100,7 @@ FILES\n\n"},{"id":"390210","messageId":"xmqq8sm08n2j.fsf@gitster-ct.c.googlers.com","threadId":"52668","inReplyTo":"20200120175210.GA3989@coredump.intra.peff.net","subject":"Re: [PATCH v4 1/5] doc: move author and committer information to git-commit(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-21T22:24:52Z","receivedAt":"2020-01-21T22:25:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King <peff@peff.net> writes:\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> it stayed here, so now it's duplicated. Should the old one be dropped?\n> Or is moving the new text a leftover mistake from rebasing (IIRC, in\n> your original you dropped this whole \"here's how commits work\" section).\n\nAh, you spotted the same thing.\n"},{"id":"390211","messageId":"xmqq4kwo8mkh.fsf@gitster-ct.c.googlers.com","threadId":"52668","inReplyTo":"20200120173343.4102954-4-sandals@crustytoothpaste.net","subject":"Re: [PATCH v4 3/5] doc: provide guidance on user.name format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-01-21T22:35:42Z","receivedAt":"2020-01-21T22:35:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> diff --git a/Documentation/config/user.txt b/Documentation/config/user.txt\n> index a1f80e823c..f0edb06329 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.\n> +See linkgit:git-commit[1] for more information on these settings and\n\nThe environment variables section of git(1) seems to be much more\ndetailed than what we have in git-commit(1) after the two previous\nsteps.  I do not mind keeping the reference to git-commit here, but\nI think it is also OK to refer to the description in git(1) there,\ntoo.\n\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index 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\nGood.\n"}]}