{"thread":{"id":"52175","subject":"[PATCH v3 0/4] Documentation for common user misconceptions","startedAt":"2019-11-02T19:26:49Z","lastAt":"2020-01-16T23:35:16Z","messageCount":25,"participants":["brian m. carlson","rsbecker@nexbridge.com","Jakub Narebski","Jeff King","Junio C Hamano","Emily Shaffer"],"isPatch":true,"patchVersion":3,"patchTotal":4},"messages":[{"id":"385317","messageId":"20191102192615.10013-1-sandals@crustytoothpaste.net","threadId":"52175","inReplyTo":null,"subject":"[PATCH v3 0/4] Documentation for common user misconceptions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-02T19:26:11Z","receivedAt":"2019-11-02T19:26:49Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"This series includes four patches that update the documentation to\naddress common user misconceptions.\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 (4):\n doc: move author and committer information to git-commit(1)\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 | 39 ++++-------------------------\n Documentation/git-commit.txt | 40 +++++++++++++++++++++++++++---\n Documentation/git-update-index.txt | 16 ++++++++++++\n 5 files changed, 72 insertions(+), 38 deletions(-)\n\nRange-diff against v2:\n1: 603a9f8f9a < -: ---------- doc: provide guidance on user.name format\n-: ---------- > 1: b39b365f54 doc: move author and committer information to git-commit(1)\n-: ---------- > 2: b7d805427c doc: provide guidance on user.name format\n2: 0da41623a5 ! 3: 7644af0b07 doc: dissuade users from trying to ignore tracked files\n @@ Commit message\n pitfalls in the documentation for git update-index so that users know\n they should explore alternate solutions.\n \n + In additon, let's provide a recommended solution to dealing with the\n + common case of configuration files, since there are well-known\n + approaches used successfully in many environments.\n +\n Signed-off-by: brian m. carlson \n \n ## Documentation/git-update-index.txt ##\n @@ Documentation/git-update-index.txt: The untracked cache extension can be enabled\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 ++If the file you want to change is some sort of configuration file (say,\n ++for a build tool, IDE, or editor), a common solution is to use a\n ++templating mechanism, such as Ruby's ERB, to generate the ignored\n ++configuration file from a template stored in the repository and a source\n ++of data using a script or build step.\n +\n SEE ALSO\n --------\n3: 89fe11b951 ! 4: d096763e7a docs: mention when increasing http.postBuffer is valuable\n @@ Documentation/config/http.txt: http.postBuffer::\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.\n ++significantly since the entire buffer is allocated for even small\n ++pushes.\n \n http.lowSpeedLimit, http.lowSpeedTime::\n \tIf the HTTP transfer speed is less than 'http.lowSpeedLimit'\n"},{"id":"385318","messageId":"20191102192615.10013-3-sandals@crustytoothpaste.net","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"[PATCH v3 2/4] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-02T19:26:13Z","receivedAt":"2019-11-02T19:26:49Z","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..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 f684f7fdc2..3a69d82d52 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -467,6 +467,12 @@ 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":"385319","messageId":"20191102192615.10013-4-sandals@crustytoothpaste.net","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"[PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-02T19:26:14Z","receivedAt":"2019-11-02T19:26:49Z","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 additon, 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 \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 1c4d146a41..11230376c8 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -543,6 +543,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+If the file you want to change is some sort of configuration file (say,\n+for a build tool, IDE, or editor), a common solution is to use a\n+templating mechanism, such as Ruby's ERB, to generate the ignored\n+configuration file from a template stored in the repository and a source\n+of data using a script or build step.\n+\n SEE ALSO\n --------\n linkgit:git-config[1],\n"},{"id":"385320","messageId":"20191102192615.10013-5-sandals@crustytoothpaste.net","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"[PATCH v3 4/4] docs: mention when increasing http.postBuffer is valuable","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-02T19:26:15Z","receivedAt":"2019-11-02T19:26:51Z","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..08b375fe95 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 for even small\n+pushes.\n \n http.lowSpeedLimit, http.lowSpeedTime::\n \tIf the HTTP transfer speed is less than 'http.lowSpeedLimit'\n"},{"id":"385321","messageId":"20191102192615.10013-2-sandals@crustytoothpaste.net","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"[PATCH v3 1/4] doc: move author and committer information to git-commit(1)","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-02T19:26:12Z","receivedAt":"2019-11-02T19:26:51Z","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\nSigned-off-by: brian m. carlson \n---\n Documentation/config/user.txt | 2 +-\n Documentation/git-commit-tree.txt | 39 ++++---------------------------\n Documentation/git-commit.txt | 34 ++++++++++++++++++++++++---\n 3 files changed, 37 insertions(+), 38 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..d518dffce0 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 ::\n@@ -69,40 +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-A commit encapsulates:\n-\n-- all parent object ids\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-\n include::date-formats.txt[]\n \n Discussion\n@@ -117,6 +87,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 afa7b75a23..f684f7fdc2 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -352,9 +352,6 @@ changes to tracked files.\n \tthese files are also staged for the next commit on top\n \tof what have been staged before.\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@@ -448,6 +445,37 @@ 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+A commit encapsulates:\n+\n+- all parent object ids\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+:git-commit: 1\n+include::date-formats.txt[]\n \n DISCUSSION\n ----------\n"},{"id":"385322","messageId":"001501d591ba$1d190060$574b0120$@nexbridge.com","threadId":"52175","inReplyTo":"20191102192615.10013-4-sandals@crustytoothpaste.net","subject":"RE: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"","fromEmail":"rsbecker@nexbridge.com","sentAt":"2019-11-02T20:14:14Z","receivedAt":"2019-11-02T20:14:41Z","isPatch":true,"sender":{"key":"randall.becker@nexbridge.ca","avatar":"https://avatars.githubusercontent.com/u/28956764?v=4"},"body":"On November 2, 2019 3:26 PM, brian m. carlson wrote:\n> It is quite common for users to want to ignore the changes to a file that\nGit\n> tracks. Common scenarios for this case are IDE settings and configuration\n> files, which should generally not be tracked and possibly generated from\n> tracked files using a templating mechanism.\n> \n> However, users learn about the assume-unchanged and skip-worktree bits\n> and try to use them to do this anyway. This is problematic, because when\n> these bits are set, many operations behave as the user expects, but they\n> usually do not help when git checkout needs to replace a file.\n> \n> There is no sensible behavior in this case, because sometimes the data is\n> precious, such as certain configuration files, and sometimes it is\nirrelevant\n> data that the user would be happy to discard.\n> \n> Since this is not a supported configuration and users are prone to misuse\nthe\n> existing features for unintended purposes, causing general sadness and\n> confusion, let's document the existing behavior and the pitfalls in the\n> documentation for git update-index so that users know they should explore\n> alternate solutions.\n> \n> In additon, let's provide a recommended solution to dealing with the\n> common case of configuration files, since there are well-known approaches\n> used successfully in many environments.\n\nJust noodling about a potential solution. If we assume the use case that\nfiles are modified by an IDE that have no real relevance, but should not\ninterfere with other git operations including checkout...\n\nWhat if we introduce something like .gitignore.changes, with the same syntax\nas .gitignore. The difference is files listed in this file will not show in\ngit status (or could show as \"changes ignored\" with an option to enable\nthat. The only way to have the changes considered would be git add -f, so\ngit add . and git commit -a would not pick up the changes. From checkout's\nperspective, the file would be considered unmodified so if a change is\nincoming for that path, checkout replaces it instead of rejecting the\ncheckout, otherwise the file is untouched. Pull would act similarly. Branch\nswitching would be permitted without stashing the files - they would remain\nunchanged unless the switch modified the files.\n\nOTOH, this is a change that is most relevant to IDE users, so JGit would\nhave to implement it as well to really get any real benefit.\n\nThis does have some benefit in post-install situations as well as the IDE\nuse-case, but for that I might want to consider finer granularity, like some\nway to identify regions of files being ignored. This being a pretty deep\nrabbit hole we'd end up following.\n\nIf this idea seems reasonable, it might make a nice small project for\nsomeone, possibly me, if I could unentangle from my current hellish $DAYJOB\nproject.\n\nJust my few coins of thought.\n\nRandall\n\n\n"},{"id":"385340","messageId":"86y2wx5i1c.fsf@gmail.com","threadId":"52175","inReplyTo":"20191102192615.10013-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-03T11:13:51Z","receivedAt":"2019-11-03T11:13:59Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"\"brian m. carlson\" writes:\n\n> While at one time it made perfect sense to store information about\n> configuring author and committer information in the documentation for\n> git commit-tree, in modern Git that operation is seldom used. Most\n> users will use git commit and expect to find comprehensive documentation\n> about its use in the manual page for that command.\n>\n> Considering that there is significant confusion about how one is to use\n> the user.name and user.email variables, let's put as much documentation\n> as possible into an obvious place where users will be more likely to\n> find it.\n>\n> Signed-off-by: brian m. carlson \n> ---\n> Documentation/config/user.txt | 2 +-\n> Documentation/git-commit-tree.txt | 39 ++++---------------------------\n> Documentation/git-commit.txt | 34 ++++++++++++++++++++++++---\n> 3 files changed, 37 insertions(+), 38 deletions(-)\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\nO.K., lets refer users to the command they actually use.\n\n> user.useConfigOnly::\n> \tInstruct Git to avoid trying to guess defaults for `user.email`\n> diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt\n> index 4b90b9c12a..d518dffce0 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\nI understand this is what is extracted from the removed part (moved to\ngit-commit documentation). But I think it is not enough to understand\nhow to actually use this command; this change makes reference\ndocumentation not self contained.\n\n> OPTIONS\n> -------\n> ::\n> @@ -69,40 +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> -A commit encapsulates:\n> -\n> -- all parent object ids\n> -- author name, email and date\n> -- committer name and email and the commit time.\n\nO.K., I can understand moving this information to a better place\n(nb. what about gitglossry?).\n\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\nI'm not sure if this should not be left here, perhaps extracted into\nseparate fragment file to be included in both git-commit-tree.txt and in\ngit-commit.txt\n\nI see that we are missing the ebvious information that if GIT_*_DATE\nenvironment variables are not set, Git will use current date and time.\nIs there a place where we say what format GIT_*_DATE needs to be in?\n\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> include::date-formats.txt[]\n> \n> Discussion\n> @@ -117,6 +87,7 @@ FILES\n> SEE ALSO\n> --------\n> linkgit:git-write-tree[1]\n> +linkgit:git-commit[1]\n\nAll right.\n\n> \n> GIT\n> ---\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index afa7b75a23..f684f7fdc2 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -352,9 +352,6 @@ changes to tracked files.\n> \tthese files are also staged for the next commit on top\n> \tof what have been staged before.\n> \n> -:git-commit: 1\n> -include::date-formats.txt[]\n> -\n\nAll right, it is moved down, not removed.\n\n> EXAMPLES\n> --------\n> When recording your own work, the contents of modified files in\n> @@ -448,6 +445,37 @@ 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> +A commit encapsulates:\n> +\n> +- all parent object ids\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,\n ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis was true for `git commit-tree`, with the following synopsis\n\n git commit-tree [(-p )…​]\n git commit-tree [(-p )…​] [-S[]] [(-m )…​]\n \t\t [(-F )…​] \n\nThis is decidely *NOT true* for `git commit`:\n\n git commit [-a | --interactive | --patch] [-s] [-v] [-u] [--amend]\n \t [--dry-run] [(-c | -C | --fixup | --squash) ]\n \t [-F | -m ] [--reset-author] [--allow-empty]\n \t [--allow-empty-message] [--no-verify] [-e] [--author=]\n \t [--date=] [--cleanup=] [--[no-]status]\n \t [-i | -o] [-S[]] [--] […​]\n\nParent ids are *not* provided on the command line.\n\n> 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\nI think that this description, while perfectly fine for plumbing command\n`git commit-tree`, might be needlesly confusing for `git commit` users,\nas it describes less often common used way of providing committer and\nauthor information first.\n\nAlso in `git commit` there are *options* specifically for adjusting how\ncommitter and author information is handled: `--reuse-message=`\nand `--reedit-message=`, `--reset-author` (doesn't make sense\nalone), `--author=` and `--date=`.\n\nMaybe describe usual way first, then describe the various options and\ntheir priority?\n\n> +\n> +:git-commit: 1\n> +include::date-formats.txt[]\n> \n> DISCUSSION\n> ----------\n\nBest,\n-- \nJakub Narębski\n"},{"id":"385341","messageId":"86pni9hzl6.fsf@gmail.com","threadId":"52175","inReplyTo":"20191102192615.10013-3-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 2/4] doc: provide guidance on user.name format","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-03T13:13:57Z","receivedAt":"2019-11-03T13:14:04Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"\"brian m. carlson\" writes:\n\n> It's a frequent misconception that the user.name variable controls\n> authentication in some way, and as a result, beginning users frequently\n> attempt to change it when they're having authentication troubles.\n> Document that the convention is that this variable represents some form\n> of a human's personal name, although that is not required. In addition,\n> address concerns about whether Unicode is supported.\n>\n> Use the term \"personal name\" as this is likely to draw the intended\n> contrast, be applicable across cultures which may have different naming\n> conventions, and be easily understandable to people who do not speak\n> English as their first language. Indicate that \"some form\" is\n> conventionally used, as people may use a nickname or preferred name\n> instead of a full legal name.\n\nThis reminds me of \"Personal names around the world\" by W3C\nhttps://www.w3.org/International/questions/qa-personal-names\n\n>\n> Point users who may be confused about authentication to an appropriate\n> configuration option instead. Provide a shortened form of this\n> information in the configuration option description.\n>\n> Signed-off-by: brian m. carlson \n\nI like this change! Un-confusing users is always a win.\n\n> ---\n> Documentation/config/user.txt | 7 ++++++-\n> Documentation/git-commit.txt | 6 ++++++\n> 2 files changed, 12 insertions(+), 1 deletion(-)\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> +the `credential.username` option if you're looking for authentication\n> +credentials instead.\n\nMinor nit: should this be one paragraph or two - the linebreak after \"of\na personal name.\" looks a bit strange?\n\nNo need for a change: just idly wondering.\n\n> \n> user.useConfigOnly::\n> \tInstruct Git to avoid trying to guess defaults for `user.email`\n> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\n> index f684f7fdc2..3a69d82d52 100644\n> --- a/Documentation/git-commit.txt\n> +++ b/Documentation/git-commit.txt\n> @@ -467,6 +467,12 @@ 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\nJust ensuring that I understand it correctly: by \"constraints\" you mean\nstripping of \"<\", \">\" and \"\\n\" (and by implication \"\\0\")?\n\nShould we say anything about encoding?\n\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\nBest,\n-- \nJakub Narębski\n"},{"id":"385343","messageId":"86h83lhugj.fsf@gmail.com","threadId":"52175","inReplyTo":"20191102192615.10013-4-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-03T15:04:44Z","receivedAt":"2019-11-03T15:04:52Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"\"brian m. carlson\" writes:\n\n> It is quite common for users to want to ignore the changes to a file\n> that Git tracks. Common scenarios for this case are IDE settings and\n> configuration files, which should generally not be tracked and possibly\n> generated from tracked files using a templating mechanism.\n>\n> However, users learn about the assume-unchanged and skip-worktree bits\n> and try to use them to do this anyway. This is problematic, because\n> when these bits are set, many operations behave as the user expects, but\n> they usually do not help when git checkout needs to replace a file.\n>\n> There is no sensible behavior in this case, because sometimes the data\n> is precious, such as certain configuration files, and sometimes it is\n> irrelevant data that the user would be happy to discard.\n>\n> Since this is not a supported configuration and users are prone to\n> misuse the existing features for unintended purposes, causing general\n> sadness and confusion, let's document the existing behavior and the\n> pitfalls in the documentation for git update-index so that users know\n> they should explore alternate solutions.\n>\n> In additon, let's provide a recommended solution to dealing with the\n> common case of configuration files, since there are well-known\n> approaches used successfully in many environments.\n\nAll right, looks sensible and good thing to have.\n\n> Signed-off-by: brian m. carlson \n> ---\n> Documentation/git-update-index.txt | 16 ++++++++++++++++\n> 1 file changed, 16 insertions(+)\n>\n> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\n> index 1c4d146a41..11230376c8 100644\n> --- a/Documentation/git-update-index.txt\n> +++ b/Documentation/git-update-index.txt\n> @@ -543,6 +543,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\nWhy the change between formatting '``assume unchanged''' (with double\nquotes and space separated) and 'skip-worktree' (without quotes, and\nkebab-cased)? In the commit message you write about assume-unchanged\nand skip-worktree.\n\nI guess that follows the inconsistency in git-update-index(1) headers,\nnamely we have\n\n USING ``ASSUME UNCHANGED'' BIT\n ------------------------------\n\nbut\n\n SKIP-WORKTREE BIT\n -----------------\n\nThis incconsistency is much more viible when both names are on the same\nline, however.\n\nThis is a minor nit.\n\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\nI'm not sure if it is a place for it, but the proposed text treats\nassume-unchanged and skip-worktree as similarly unsuited for intended\npurpose. However, their failure modes are different: (ab)using the\nassume-unchanged for \"ignore changed to tracked files\" may lead to data\nloss (as changes are overwritten), while with skip-worktree the trouble\nis that some operations that should succeed (like unstashing) are\nunnecessarily blocked - but no data loss.\n\n> +\n> +If the file you want to change is some sort of configuration file (say,\n> +for a build tool, IDE, or editor), a common solution is to use a\n> +templating mechanism, such as Ruby's ERB, to generate the ignored\n> +configuration file from a template stored in the repository and a source\n> +of data using a script or build step.\n\nI would really like to see a simple example of such template, so that\neven people who are unfamiliar with Ruby's ERB can think of equivalent\nsolution for their language or toolchain of choice.\n\n> +\n> SEE ALSO\n> --------\n> linkgit:git-config[1],\n\nBest,\n-- \nJakub Narębski\n"},{"id":"385344","messageId":"86bltthsjj.fsf@gmail.com","threadId":"52175","inReplyTo":"001501d591ba$1d190060$574b0120$@nexbridge.com","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-03T15:46:08Z","receivedAt":"2019-11-03T15:46:54Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":" writes:\n\n> On November 2, 2019 3:26 PM, brian m. carlson wrote:\n>> It is quite common for users to want to ignore the changes to a file that Git\n>> tracks. Common scenarios for this case are IDE settings and configuration\n>> files, which should generally not be tracked and possibly generated from\n>> tracked files using a templating mechanism.\n>> \n>> However, users learn about the assume-unchanged and skip-worktree bits\n>> and try to use them to do this anyway. This is problematic, because when\n>> these bits are set, many operations behave as the user expects, but they\n>> usually do not help when git checkout needs to replace a file.\n[...]\n> Just noodling about a potential solution. If we assume the use case that\n> files are modified by an IDE that have no real relevance, but should not\n> interfere with other git operations including checkout...\n>\n> What if we introduce something like .gitignore.changes, with the same syntax\n> as .gitignore. The difference is files listed in this file will not show in\n> `git status` (or could show as \"changes ignored\" with an option to enable\n> that. The only way to have the changes considered would be `git add -f`, so\n> `git add .` and `git commit -a` would not pick up the changes.\n[...]\n\nI think it would be better and easier to add new attribute and use\n.gitattributes instead of a new .gitignore.changes (and its\nper-repository, per-user and system-wide version).\n\n> If this idea seems reasonable, it might make a nice small project for\n> someone, possibly me, if I could unentangle from my current hellish $DAYJOB\n> project.\n\nI wish you luck.\n\nThe fact that it was nod done yet may mean that there are some annoying\ncorner-cases in the concept, or that it is not commonly useful... or\nmaybe that is the problem that needs reframing.\n\nBest,\n-- \nJakub Narębski\n"},{"id":"385348","messageId":"20191103185908.GA32531@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"86h83lhugj.fsf@gmail.com","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-03T18:59:08Z","receivedAt":"2019-11-03T18:59:16Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-11-03 at 15:04:44, Jakub Narebski wrote:\n> Why the change between formatting '``assume unchanged''' (with double\n> quotes and space separated) and 'skip-worktree' (without quotes, and\n> kebab-cased)? In the commit message you write about assume-unchanged\n> and skip-worktree.\n> \n> I guess that follows the inconsistency in git-update-index(1) headers,\n> namely we have\n> \n> USING ``ASSUME UNCHANGED'' BIT\n> ------------------------------\n> \n> but\n> \n> SKIP-WORKTREE BIT\n> -----------------\n> \n> This incconsistency is much more viible when both names are on the same\n> line, however.\n\nYeah, I can change them to make them consistent. I did preserve the\nexisting formatting for both, as you mentioned.\n\n> I'm not sure if it is a place for it, but the proposed text treats\n> assume-unchanged and skip-worktree as similarly unsuited for intended\n> purpose. However, their failure modes are different: (ab)using the\n> assume-unchanged for \"ignore changed to tracked files\" may lead to data\n> loss (as changes are overwritten), while with skip-worktree the trouble\n> is that some operations that should succeed (like unstashing) are\n> unnecessarily blocked - but no data loss.\n\nI agree the failure modes can be different, but from my experience there\nare people who have seen checkout failures with both bits set\nindependently. I'm not exactly sure what those cases are, but folks do\nsee them on Stack Overflow quite frequently.\n\nEven if there is a difference in failure modes, I'd rather encourage\npeople to just not use this mechanism rather than explain why or in\nwhich cases it won't do what you want.\n\n> I would really like to see a simple example of such template, so that\n> even people who are unfamiliar with Ruby's ERB can think of equivalent\n> solution for their language or toolchain of choice.\n\nI hesitated to mention ERB, but I wasn't sure that folks would know what\nwe meant by a \"templating mechanism\". The reason I had chosen to\nmention it is that someone could search for \"Ruby ERB\" and find out what\nit looked like and then look for an option in their own language.\n\nMy concern with adding such a template is that an example will likely\ngrow this section quite a bit, and it's meant as a short aside to help\npeople avoid making a common mistake and guide them to a proper solution\nrather than a comprehensive howto. I'm planning on adding a FAQ\ndocument in the future that covers a lot of these issues in more detail\nand helps folks figure out solutions to common problems, and I'd prefer\nto explain this more in depth there.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"385349","messageId":"20191103192352.GB32531@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"86pni9hzl6.fsf@gmail.com","subject":"Re: [PATCH v3 2/4] doc: provide guidance on user.name format","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-03T19:23:52Z","receivedAt":"2019-11-03T19:23:59Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-11-03 at 13:13:57, Jakub Narebski wrote:\n> This reminds me of \"Personal names around the world\" by W3C\n> https://www.w3.org/International/questions/qa-personal-names\n\nI hadn't read that document before, but it's definitely the approach I\nwas going for. People all over the world use Git, and we should make it\nas usable for all of those people as we can.\n\n> Minor nit: should this be one paragraph or two - the linebreak after \"of\n> a personal name.\" looks a bit strange?\n> \n> No need for a change: just idly wondering.\n\nGood question. I had explained this in my original patch but had to\nreformat the patch and forgot to include this.\n\nThe existing text uses a line break after each sentence, and in AsciiDoc\nthat doesn't introduce a new paragraph; only a blank line does that. I\nopted to keep this consistent with the rest of the description of this\nitem.\n\n> Just ensuring that I understand it correctly: by \"constraints\" you mean\n> stripping of \"<\", \">\" and \"\\n\" (and by implication \"\\0\")?\n\nYes, that's correct.\n\n> Should we say anything about encoding?\n\nI don't think it's necessary; since we told people that arbitrary\nUnicode is permitted, hopefully they will determine that they should use\nUTF-8, or, for Windows environment variables, UTF-16. Unfortunately,\nthere's not a good way to get UTF-8 environment variables in Windows, so\n\"Unicode\" is the best we can do there.\n\nI'm happy to gloss over the fact that they can use something else\nbecause (a) while they can, they should not and (b) if they do, they'll\nknow that they're obviously restricted to that subset of Unicode.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"385350","messageId":"861ruoiw97.fsf@gmail.com","threadId":"52175","inReplyTo":"20191103185908.GA32531@camp.crustytoothpaste.net","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-03T19:40:36Z","receivedAt":"2019-11-03T19:40:42Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"\"brian m. carlson\" writes:\n> On 2019-11-03 at 15:04:44, Jakub Narebski wrote:\n\n>> Why the change between formatting '``assume unchanged''' (with double\n>> quotes and space separated) and 'skip-worktree' (without quotes, and\n>> kebab-cased)? In the commit message you write about assume-unchanged\n>> and skip-worktree.\n>> \n>> I guess that follows the inconsistency in git-update-index(1) headers,\n>> namely we have\n>> \n>> USING ``ASSUME UNCHANGED'' BIT\n>> ------------------------------\n>> \n>> but\n>> \n>> SKIP-WORKTREE BIT\n>> -----------------\n>> \n>> This inconsistency is much more visible when both names are on the same\n>> line, however.\n>\n> Yeah, I can change them to make them consistent. I did preserve the\n> existing formatting for both, as you mentioned.\n\nThanks in advance. This inconsistence just looks strange in one line.\n\n>> I'm not sure if it is a place for it, but the proposed text treats\n>> assume-unchanged and skip-worktree as similarly unsuited for intended\n>> purpose. However, their failure modes are different: (ab)using the\n>> assume-unchanged for \"ignore changed to tracked files\" may lead to data\n>> loss (as changes are overwritten), while with skip-worktree the trouble\n>> is that some operations that should succeed (like unstashing) are\n>> unnecessarily blocked - but no data loss.\n>\n> I agree the failure modes can be different, but from my experience there\n> are people who have seen checkout failures with both bits set\n> independently. I'm not exactly sure what those cases are, but folks do\n> see them on Stack Overflow quite frequently.\n>\n> Even if there is a difference in failure modes, I'd rather encourage\n> people to just not use this mechanism rather than explain why or in\n> which cases it won't do what you want.\n\nWhat I wanted to say here is that if you really, really need to abuse\nthose mechanism for \"ignore tracked files changes\", it is better to use\nskip-worktree bit -- at least you wouldn't loose your data (your\nprecious changes).\n\nNb. I have experimented with both assume-unchanged and skip-worktree,\nso I know their annoyances, but I have not had a need to use them.\n\n>> I would really like to see a simple example of such template, so that\n>> even people who are unfamiliar with Ruby's ERB can think of equivalent\n>> solution for their language or toolchain of choice.\n>\n> I hesitated to mention ERB, but I wasn't sure that folks would know what\n> we meant by a \"templating mechanism\". The reason I had chosen to\n> mention it is that someone could search for \"Ruby ERB\" and find out what\n> it looked like and then look for an option in their own language.\n\nI would like to see not an example of template, but example how such\ntemplate can be used in place of \"ignore tracked files change\".\n\n> My concern with adding such a template is that an example will likely\n> grow this section quite a bit, and it's meant as a short aside to help\n> people avoid making a common mistake and guide them to a proper solution\n> rather than a comprehensive howto. I'm planning on adding a FAQ\n> document in the future that covers a lot of these issues in more detail\n> and helps folks figure out solutions to common problems, and I'd prefer\n> to explain this more in depth there.\n\nYour proposed change:\n\n +If the file you want to change is some sort of configuration file (say,\n +for a build tool, IDE, or editor), a common solution is to use a\n +templating mechanism, such as Ruby's ERB, to generate the ignored\n +configuration file from a template stored in the repository and a source\n +of data using a script or build step.\n\nI don't see how such templating mechanism could be used. You have some\nkind of configuration file with placeholders comitted, and you have a\nversion of this file with local changes -- how templating mechanism\ncould solve this? I would like to see few lines of an example and its\nuse.\n\n\nAlterantives:\n~~~~~~~~~~~~~\n\nIn our build system, we have versioned Makefile, and not versioned\nconfig.mak (with local configuration), which is included by Makefile.\n\nIn many cases using environment variables to provide local changes is\nrecommended, something like e.g.\n\n AWS::S3::Base.establish_connection!(\n :access_key_id => ENV['S3_KEY'],\n :secret_access_key => ENV['S3_SECRET']\n )\n\n\nBest,\n-- \nJakub Narębski\n"},{"id":"385356","messageId":"20191103214608.GC32531@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"861ruoiw97.fsf@gmail.com","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-03T21:46:08Z","receivedAt":"2019-11-03T21:46:20Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-11-03 at 19:40:36, Jakub Narebski wrote:\n> Your proposed change:\n> \n> +If the file you want to change is some sort of configuration file (say,\n> +for a build tool, IDE, or editor), a common solution is to use a\n> +templating mechanism, such as Ruby's ERB, to generate the ignored\n> +configuration file from a template stored in the repository and a source\n> +of data using a script or build step.\n> \n> I don't see how such templating mechanism could be used. You have some\n> kind of configuration file with placeholders comitted, and you have a\n> version of this file with local changes -- how templating mechanism\n> could solve this? I would like to see few lines of an example and its\n> use.\n> \n> Alterantives:\n> ~~~~~~~~~~~~~\n> \n> In our build system, we have versioned Makefile, and not versioned\n> config.mak (with local configuration), which is included by Makefile.\n\nEssentially, make and shell support this by themselves, but if, for\nexample, I wanted to adjust my dotfiles to set the email address once\nand for all, I could create the following files:\n\n.muttrc.erb:\n----\nmy_hdr From: brian m. carlson <<%= data[\"email\"] -%>>\n----\n\n.gitconfig.erb:\n----\n[user]\nname = brian m. carlson\nemail = <%= data[\"email\"] -%>\n----\n\ntemplate.rb:\n----\n#!/usr/bin/env ruby\n\nrequire 'erb'\n\nclass Template\n def name\n @name ||= 0\n @name += 1\n \"name_a#{@name}\"\n end\n\n def data\n ENV.map { |k, v| [k.downcase, v] }.to_h\n end\n\n def erb(file)\n ERB.new(File.read(file), nil, '-', name).result(binding)\n end\nend\n\nputs Template.new.erb(ARGV[0])\n----\n\nand then run:\n\nEMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc\nEMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig\n\nThe problem that folks tend to have is that they have a single editor or\nIDE project file, such as an XCode configuration file, that can't be\nsplit among multiple files, some of which are checked in and some of\nwhich are not. Other situations are generating a configuration file for\na web server like nginx in development, which may of course differ\ndepending on where the user has checked out the repository.\n\nUsing some sort of file like a config.mak is a fine solution, but many\nprograms don't support that, so it's necessary to create a template for\nthe build process and add a script to generate it. The actual\nconfiguration values can come from the environment, the user's\ngitconfig, a YAML file the user has configured, or anywhere else that\nmakes sense.\n\nAs you can see, the example is large and unwieldy, and would not make a\ngood inclusion in the man page. I included that paragraph because Peff\nstated that it would be nice if we could offer people a solution, but\nI'd rather drop it if it's too confusing without an example.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"385434","messageId":"20191104221822.GA22367@sigill.intra.peff.net","threadId":"52175","inReplyTo":"20191102192615.10013-2-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-11-04T22:18:22Z","receivedAt":"2019-11-04T22:18:25Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Nov 02, 2019 at 07:26:12PM +0000, brian m. carlson wrote:\n\n> While at one time it made perfect sense to store information about\n> configuring author and committer information in the documentation for\n> git commit-tree, in modern Git that operation is seldom used. Most\n> users will use git commit and expect to find comprehensive documentation\n> about its use in the manual page for that command.\n> \n> Considering that there is significant confusion about how one is to use\n> the user.name and user.email variables, let's put as much documentation\n> as possible into an obvious place where users will be more likely to\n> find it.\n\nI think we might want to keep documentation that gets too low-level out\nof git-commit(1).\n\nSo for instance, this part that got moved from commit-tree:\n\n> +A commit encapsulates:\n> +\n> +- all parent object ids\n> +- author name, email and date\n> +- committer name and email and the commit time.\n> +\n\nI think could just stay there.\n\nThe part just below that:\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\nwould be appropriate in git-commit. Though possibly they should just be\nbroken out into an ENVIRONMENT VARIABLES section.\n\nI thought we already did so in git.txt, but it looks like it just refers\nto commit-tree (and if we don't do anything more drastic, I think you'd\nprobably want to update that reference). Since these do affect multiple\ncommands, I wonder if it would make sense to define them there in\ngit.txt, giving a more user-facing description. Something like:\n\n GIT_COMMITTER_NAME::\n\tThe human-readable name used in the committer identity when\n\tcreating commit or tags objects, or when writing reflogs.\n\tOverrides the user.name config.\n\nand so forth for COMMITTER_EMAIL, AUTHOR_NAME, etc.\n\n-Peff\n"},{"id":"385435","messageId":"20191104222416.GB22367@sigill.intra.peff.net","threadId":"52175","inReplyTo":"20191103185908.GA32531@camp.crustytoothpaste.net","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-11-04T22:24:16Z","receivedAt":"2019-11-04T22:24:20Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, Nov 03, 2019 at 06:59:08PM +0000, brian m. carlson wrote:\n\n> > I would really like to see a simple example of such template, so that\n> > even people who are unfamiliar with Ruby's ERB can think of equivalent\n> > solution for their language or toolchain of choice.\n> \n> I hesitated to mention ERB, but I wasn't sure that folks would know what\n> we meant by a \"templating mechanism\". The reason I had chosen to\n> mention it is that someone could search for \"Ruby ERB\" and find out what\n> it looked like and then look for an option in their own language.\n\nI don't mind what is here, but I might even suggest going slightly in\nthe opposite direction. Say something like:\n\n For example, you the repository can include a sample config file that\n can then be copied into the ignored name and modified.\n\nwhich points people in the right direction without giving specifics. But\nif you did want to go further, you can then say:\n\n The repository can even include a script to treat the sample file as a\n template, modifying and copying it automatically (e.g., a Ruby script\n using an ERB template).\n\nor something.\n\n> My concern with adding such a template is that an example will likely\n> grow this section quite a bit, and it's meant as a short aside to help\n> people avoid making a common mistake and guide them to a proper solution\n> rather than a comprehensive howto.\n\nYeah. I don't think we should get into best practices for using ERB.\n\n-Peff\n"},{"id":"385436","messageId":"20191104222634.GC22367@sigill.intra.peff.net","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2019-11-04T22:26:34Z","receivedAt":"2019-11-04T22:26:42Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:\n\n> This series includes four patches that update the documentation to\n> address common user misconceptions.\n> \n> Changes 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\nThanks. I think this is an improvement over v1, but I'm still a little\niffy on some of the other movement in the first patch.\n\nTBH, I don't think it's making anything _worse_, but I think it\nhighlights how some of our documentation is a mish-mash of low-level and\nhigh-level details. ;) So it might be a good opportunity to at least\nclean up the documentation around ident environment variables.\n\n-Peff\n"},{"id":"385440","messageId":"20191104235242.GD32531@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"20191104222416.GB22367@sigill.intra.peff.net","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-04T23:52:42Z","receivedAt":"2019-11-04T23:52:49Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-11-04 at 22:24:16, Jeff King wrote:\n> On Sun, Nov 03, 2019 at 06:59:08PM +0000, brian m. carlson wrote:\n> \n> > > I would really like to see a simple example of such template, so that\n> > > even people who are unfamiliar with Ruby's ERB can think of equivalent\n> > > solution for their language or toolchain of choice.\n> > \n> > I hesitated to mention ERB, but I wasn't sure that folks would know what\n> > we meant by a \"templating mechanism\". The reason I had chosen to\n> > mention it is that someone could search for \"Ruby ERB\" and find out what\n> > it looked like and then look for an option in their own language.\n> \n> I don't mind what is here, but I might even suggest going slightly in\n> the opposite direction. Say something like:\n> \n> For example, you the repository can include a sample config file that\n> can then be copied into the ignored name and modified.\n> \n> which points people in the right direction without giving specifics. But\n> if you did want to go further, you can then say:\n> \n> The repository can even include a script to treat the sample file as a\n> template, modifying and copying it automatically (e.g., a Ruby script\n> using an ERB template).\n> \n> or something.\n\nI think this is a nice change. It summarizes the proposed solution\nwithout needing to be specific.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"385441","messageId":"86imnzgoll.fsf@gmail.com","threadId":"52175","inReplyTo":"20191103214608.GC32531@camp.crustytoothpaste.net","subject":"Re: [PATCH v3 3/4] doc: dissuade users from trying to ignore tracked files","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2019-11-05T00:21:10Z","receivedAt":"2019-11-05T00:21:19Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"\"brian m. carlson\" writes:\n> On 2019-11-03 at 19:40:36, Jakub Narebski wrote:\n>>\n>> Your proposed change:\n>> \n>> +If the file you want to change is some sort of configuration file (say,\n>> +for a build tool, IDE, or editor), a common solution is to use a\n>> +templating mechanism, such as Ruby's ERB, to generate the ignored\n>> +configuration file from a template stored in the repository and a source\n>> +of data using a script or build step.\n>> \n>> I don't see how such templating mechanism could be used. You have some\n>> kind of configuration file with placeholders comitted, and you have a\n>> version of this file with local changes -- how templating mechanism\n>> could solve this? I would like to see few lines of an example and its\n>> use.\n>> \n>> Alternatives:\n>> ~~~~~~~~~~~~~\n>> \n>> In our build system, we have versioned Makefile, and not versioned\n>> config.mak (with local configuration), which is included by Makefile.\n>\n> Essentially, make and shell support this by themselves, but if, for\n> example, I wanted to adjust my dotfiles to set the email address once\n> and for all, I could create the following files:\n>\n> .muttrc.erb:\n> ----\n> my_hdr From: brian m. carlson <<%= data[\"email\"] -%>>\n> ----\n>\n> .gitconfig.erb:\n> ----\n> [user]\n> name = brian m. carlson\n> email = <%= data[\"email\"] -%>\n> ----\n\nAll right, the above might be useful as an example (well, one of those),\nbut might be not necessary if the description of preferred solution is\nstated in more detail. I think it is better to start with generics,\ni.e. track template, and generate untracked file, then provide examples\nlike Ruby's ERB.\n\n> template.rb:\n> ----\n> #!/usr/bin/env ruby\n>\n> require 'erb'\n>\n> class Template\n> def name\n> @name ||= 0\n> @name += 1\n> \"name_a#{@name}\"\n> end\n>\n> def data\n> ENV.map { |k, v| [k.downcase, v] }.to_h\n> end\n>\n> def erb(file)\n> ERB.new(File.read(file), nil, '-', name).result(binding)\n> end\n> end\n>\n> puts Template.new.erb(ARGV[0])\n> ----\n\nThis is certainly too much detail.\n\n> and then run:\n>\n> EMAIL=sandals@crustytoothpaste.net template.rb .muttrc.erb >.muttrc\n> EMAIL=sandals@crustytoothpaste.net template.rb .gitconfig.erb >.gitconfig\n\nThat could be kept as an example, after simplification.\n\n> The problem that folks tend to have is that they have a single editor or\n> IDE project file, such as an XCode configuration file, that can't be\n> split among multiple files, some of which are checked in and some of\n> which are not. Other situations are generating a configuration file for\n> a web server like nginx in development, which may of course differ\n> depending on where the user has checked out the repository.\n\nAll right.\n\n> Using some sort of file like a config.mak is a fine solution, but many\n> programs don't support that, so it's necessary to create a template for\n> the build process and add a script to generate it. The actual\n> configuration values can come from the environment, the user's\n> gitconfig, a YAML file the user has configured, or anywhere else that\n> makes sense.\n\nI still think that config.mak (or equivalent) solution might be worth\nmentioning in passing.\n\n> As you can see, the example is large and unwieldy, and would not make a\n> good inclusion in the man page. I included that paragraph because Peff\n> stated that it would be nice if we could offer people a solution, but\n> I'd rather drop it if it's too confusing without an example.\n\nI think it can be done even without example, but without example it\nwould need careful crafting of the wording.\n\nBest,\n-- \nJakub Narębski\n"},{"id":"385509","messageId":"xmqqwocdwyy1.fsf@gitster-ct.c.googlers.com","threadId":"52175","inReplyTo":"20191104221822.GA22367@sigill.intra.peff.net","subject":"Re: [PATCH v3 1/4] doc: move author and committer information to git-commit(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-06T01:55:34Z","receivedAt":"2019-11-06T01:55:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I think we might want to keep documentation that gets too low-level out\n> of git-commit(1).\n>\n> So for instance, this part that got moved from commit-tree:\n>\n>> +A commit encapsulates:\n>> +\n>> +- all parent object ids\n>> +- author name, email and date\n>> +- committer name and email and the commit time.\n>> +\n>\n> I think could just stay there.\n\nMe too ;-)\n\n> ... I wonder if it would make sense to define them there in\n> git.txt, giving a more user-facing description. Something like:\n>\n> GIT_COMMITTER_NAME::\n> \tThe human-readable name used in the committer identity when\n> \tcreating commit or tags objects, or when writing reflogs.\n> \tOverrides the user.name config.\n>\n> and so forth for COMMITTER_EMAIL, AUTHOR_NAME, etc.\n\nYup, I like that. Then either commit-tree, commit etc. can refer to\nthe environment variables section of linkgit:git[1], or perhaps assume\nthat the readers know that anything common across all subcommands\nare there in linkgit:git[1] (I prefer the former).\n\nThanks.\n\n\n"},{"id":"385510","messageId":"xmqqsgn1wyt2.fsf@gitster-ct.c.googlers.com","threadId":"52175","inReplyTo":"20191104222634.GC22367@sigill.intra.peff.net","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-06T01:58:33Z","receivedAt":"2019-11-06T01:58:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> Thanks. I think this is an improvement over v1, but I'm still a little\n> iffy on some of the other movement in the first patch.\n>\n> TBH, I don't think it's making anything _worse_, but I think it\n> highlights how some of our documentation is a mish-mash of low-level and\n> high-level details. ;) So it might be a good opportunity to at least\n> clean up the documentation around ident environment variables.\n\nYeah, I hate to suggest another round, but agree with your comments\non 1/4 wrt the way how and the place where the environment variables\nare explained, which invalidates the changes in 2/4. Fortunately\n3/4 and 4/4 are unaffected ;-)\n\nThanks.\n"},{"id":"385515","messageId":"20191106021935.GF32531@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"xmqqsgn1wyt2.fsf@gitster-ct.c.googlers.com","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2019-11-06T02:19:35Z","receivedAt":"2019-11-06T02:19:43Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2019-11-06 at 01:58:33, Junio C Hamano wrote:\n> Jeff King writes:\n> \n> > Thanks. I think this is an improvement over v1, but I'm still a little\n> > iffy on some of the other movement in the first patch.\n> >\n> > TBH, I don't think it's making anything _worse_, but I think it\n> > highlights how some of our documentation is a mish-mash of low-level and\n> > high-level details. ;) So it might be a good opportunity to at least\n> > clean up the documentation around ident environment variables.\n> \n> Yeah, I hate to suggest another round, but agree with your comments\n> on 1/4 wrt the way how and the place where the environment variables\n> are explained, which invalidates the changes in 2/4. Fortunately\n> 3/4 and 4/4 are unaffected ;-)\n\nYeah, I agree another round is warranted, and it's not the end of the\nworld: it'll get into 2.25 either way. I'll try to get a reroll out in\nthe next few days.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"},{"id":"385520","messageId":"xmqqpni5vgns.fsf@gitster-ct.c.googlers.com","threadId":"52175","inReplyTo":"20191106021935.GF32531@camp.crustytoothpaste.net","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2019-11-06T03:15:51Z","receivedAt":"2019-11-06T03:15:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> On 2019-11-06 at 01:58:33, Junio C Hamano wrote:\n>> Jeff King writes:\n>> \n>> > Thanks. I think this is an improvement over v1, but I'm still a little\n>> > iffy on some of the other movement in the first patch.\n>> >\n>> > TBH, I don't think it's making anything _worse_, but I think it\n>> > highlights how some of our documentation is a mish-mash of low-level and\n>> > high-level details. ;) So it might be a good opportunity to at least\n>> > clean up the documentation around ident environment variables.\n>> \n>> Yeah, I hate to suggest another round, but agree with your comments\n>> on 1/4 wrt the way how and the place where the environment variables\n>> are explained, which invalidates the changes in 2/4. Fortunately\n>> 3/4 and 4/4 are unaffected ;-)\n>\n> Yeah, I agree another round is warranted, and it's not the end of the\n> world: it'll get into 2.25 either way. I'll try to get a reroll out in\n> the next few days.\n\nThanks. I also agree with what Peff and you said on 3/4 wrt the\naddition of \"ship template, tweak it into an untracked config that\ngets used\".\n\n"},{"id":"389930","messageId":"20200116210857.GJ181522@google.com","threadId":"52175","inReplyTo":"20191102192615.10013-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"Emily Shaffer","fromEmail":"emilyshaffer@google.com","sentAt":"2020-01-16T21:08:57Z","receivedAt":"2020-01-16T21:09:04Z","isPatch":true,"sender":{"key":"nasamuffin@google.com","avatar":"https://avatars.githubusercontent.com/u/1606826?v=4"},"body":"On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:\n> This series includes four patches that update the documentation to\n> address common user misconceptions.\n\nHm, is this still waiting for a reroll? Someone just ran into the\nuser.name/username confusion in #git-devel today:\nhttps://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79\n\n - Emily\n"},{"id":"389957","messageId":"20200116233507.GY6570@camp.crustytoothpaste.net","threadId":"52175","inReplyTo":"20200116210857.GJ181522@google.com","subject":"Re: [PATCH v3 0/4] Documentation for common user misconceptions","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2020-01-16T23:35:07Z","receivedAt":"2020-01-16T23:35:16Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2020-01-16 at 21:08:57, Emily Shaffer wrote:\n> On Sat, Nov 02, 2019 at 07:26:11PM +0000, brian m. carlson wrote:\n> > This series includes four patches that update the documentation to\n> > address common user misconceptions.\n> \n> Hm, is this still waiting for a reroll? Someone just ran into the\n> user.name/username confusion in #git-devel today:\n> https://colabti.org/irclogger/irclogger_log/git-devel?date=2020-01-16#l79\n\nYeah, it is. I have one, but haven't sent it out. I'll plan to do so\nthis weekend.\n-- \nbrian m. carlson: Houston, Texas, US\nOpenPGP: https://keybase.io/bk2204\n"}]}