{"thread":{"id":"53489","subject":"[RFC PATCH 2/6] Add bit on extending git to Hacking Git","startedAt":"2020-05-17T02:24:19Z","lastAt":"2020-06-01T23:56:24Z","messageCount":42,"participants":["Kenneth Lorber","Abhishek Kumar","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":6},"messages":[{"id":"397992","messageId":"1589681624-36969-3-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 2/6] Add bit on extending git to Hacking Git","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:40Z","receivedAt":"2020-05-17T02:24:19Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nThe Hacking Git section of the user manual is the logical place to look\nfor information on extending Gut, so add a short section of links to\nplaces where that information actually lives.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/user-manual.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 833652983f..2144246444 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4049,6 +4049,14 @@ and that is what higher level `git merge -s resolve` is implemented with.\n This chapter covers internal details of the Git implementation which\n probably only Git developers need to understand.\n \n+If you are extending Git using hooks, writing new tools, or otherwise\n+looking for technical information but not hacking Git itself, the following\n+documents may be what you are really looking for:\n+\n+* hooks: linkgit:githooks[5]\n+* attributes: linkgit:gitattributes[5]\n+* new tools: linkgit:git-sh-setup[1]\n+\n [[object-details]]\n === Object storage format\n \n-- \n2.17.1\n\n"},{"id":"397993","messageId":"1589681624-36969-2-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 1/6] Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:39Z","receivedAt":"2020-05-17T02:24:21Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nThe user manual glossary entry for hooks now knows about core.hooksPath.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/glossary-content.txt | 10 ++++++----\n 1 file changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 090c888335..37147db1bc 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -206,10 +206,12 @@ for a more flexible and robust system to do the same thing.\n \tto optional scripts that allow a developer to add functionality or\n \tchecking. Typically, the hooks allow for a command to be pre-verified\n \tand potentially aborted, and allow for a post-notification after the\n-\toperation is done. The hook scripts are found in the\n-\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n-\tremoving the `.sample` suffix from the filename. In earlier versions\n-\tof Git you had to make them executable.\n+\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n+\tor in any directory specified by the `core.hooksPath` configuration\n+\tvariable. The sample scripts are enabled by simply\n+\tremoving the `.sample` suffix from the filename. In earlier versions\n+\tof Git you had to make the sample scripts executable manually.\n+\tHook scripts must be executable. See linkgit:githooks[5] for details.\n \n [[def_index]]index::\n \tA collection of files with stat information, whose contents are stored\n-- \n2.17.1\n\n"},{"id":"397994","messageId":"1589681624-36969-6-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 5/6] Tell config.txt about NAMESPACE COLLISIONS","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:43Z","receivedAt":"2020-05-17T02:24:21Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nAdd a link to the NAMESPACE COLLISIONS information where git help config\nonly mentioned the issue without supplying any guidance for how to do that.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/config.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ef0768b91a..1e819c26f0 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -310,7 +310,9 @@ in the appropriate manual page.\n Other git-related tools may and do use their own variables. When\n inventing new variables for use in your own tool, make sure their\n names do not conflict with those that are used by Git itself and\n-other popular tools, and describe them in your documentation.\n+other popular tools, and describe them in your documentation. See\n+'NAMESPACE COLLISIONS' in linkgit:gitrepository-layout[5] for guidelines\n+to prevent such conflicts.\n \n include::config/advice.txt[]\n \n-- \n2.17.1\n\n"},{"id":"397995","messageId":"1589681624-36969-5-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 4/6] Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:42Z","receivedAt":"2020-05-17T02:24:35Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/gitrepository-layout.txt | 3 ++-\n 1 file changed, 2 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex a84a4df513..8050e8cc1f 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -290,9 +290,10 @@ worktrees//locked::\n worktrees//config.worktree::\n \tWorking directory specific configuration file.\n \n-include::technical/namespace-collisions.txt[]\n include::technical/repository-version.txt[]\n \n+include::technical/namespace-collisions.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-init[1],\n-- \n2.17.1\n\n"},{"id":"397996","messageId":"1589681624-36969-4-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 3/6] Add namespace collision avoidance guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:41Z","receivedAt":"2020-05-17T02:24:35Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nAdd a file of guidelines to prevent the namespace collisions\nmentioned in git help config without any guidance.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/gitrepository-layout.txt | 1 +\n .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n 2 files changed, 87 insertions(+)\n create mode 100644 Documentation/technical/namespace-collisions.txt\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 1a2ef4c150..a84a4df513 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -290,6 +290,7 @@ worktrees//locked::\n worktrees//config.worktree::\n \tWorking directory specific configuration file.\n \n+include::technical/namespace-collisions.txt[]\n include::technical/repository-version.txt[]\n \n SEE ALSO\ndiff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt\nnew file mode 100644\nindex 0000000000..fb79c82a73\n--- /dev/null\n+++ b/Documentation/technical/namespace-collisions.txt\n@@ -0,0 +1,86 @@\n+gitattributes\n+\n+\n+NAMESPACE COLLISIONS\n+--------------------\n+Git uses identifiers in a number of different namespaces:\n+\n+* environment variables\n+* files in $GIT_DIR\n+* files in the working trees\n+* config sections\n+* hooks\n+* attributes\n+\n+In order to reduce the chance of collisions between names Git uses\n+and those used by other entities (users, groups, and extension authors),\n+the following are recommended best practices.\n+\n+Names reserved to Git:\n+\n+* file or directory names ending with `.lock`\n+* file or directory names starting with `.git`\n+* filenames in $GIT_DIR\n+* directory names in $GIT_DIR unless allowed by a rule below\n+* environment variables starting with `GIT_`\n+* configuration file sections unless allowed by a rule below\n+* file or directory names in `$GIT_DIR/hooks` unless allowed by a rule below\n+* attributes unless allowed by a rule below\n+\n+\n+Names reserved for individual users:\n+\n+* The directory `$GIT_DIR/my`\n+* Environment variables starting with `GIT_MY_`\n+* Configuration section `my`\n+* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n+* Attributes starting with `my_`\n+\n+Names reserved for individual repos:\n+\n+* The directory `$GIT_DIR/this`\n+* Environment variables starting with `GIT_THIS_`\n+* Configuration section `this`\n+* Files or directories in `$GIT_DIR/hooks` starting with `this_`\n+* Attributes starting with `this_`\n+\n+Names reserved for the lowest level group of people:\n+\n+* The directory `$GIT_DIR/our`\n+* Environment variables starting with `GIT_OUR_`\n+* Configuration section `our`\n+* Files or directories in `$GIT_DIR/hooks` starting with `our_`\n+* Attributes starting with `our_`\n+\n+Names reserved for larger groups of people, for companies,\n+or for extensions that are distributed outside of the originating group:\n+\n+$ID is defined as a reverse DNS-style name, with dots replaced by\n+underscores (preferably) or by hyphens (if necessary). The $ID\n+can have as many sections as possible, thus `com.example.sitename.projectid`\n+is perfectly reasonable. Use of a name based on a domain you control is\n+highly recommended; if you do not control a domain, constructing the base of $ID\n+from your email address is a reasonable alternative, but use double delimiters\n+in place of the @ sign; for example: `com.example--root.project`\n+\n+* The directory $GIT_DIR/$ID\n+* Environment variables starting with `GIT__$ID_` (note two underscores)\n+* Configuration section `GIT--$ID`\n+* Files or directories in `$GIT_DIR/hooks` starting with $ID\n+* Attributes starting with `git__` (note two underscores)\n+\n+Aliases\n+~~~~~~~\n+Aliases are a special case. Users need to type them so they should be\n+short, but there is no way to prevent such short names from colliding.\n+So the documentation or installer should construct something like:\n+\n+ [alias]\n+ test = !git my-test\n+ my-test = !echo made it\n+\n+while detecting collisions for the short name. Then users or local\n+policy can deal with collisions on the short name.\n+\n+This is not meant to cover every possible use case - a policy that\n+detailed would be ignored and thus of no use. Please play nicely.\n-- \n2.17.1\n\n"},{"id":"397997","messageId":"1589681624-36969-1-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":null,"subject":"[RFC PATCH 0/6] various documentation bits","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:38Z","receivedAt":"2020-05-17T02:24:35Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nThis started as an effort to understand this section of config.txt:\n When inventing new variables for use in your own tool, make sure their\n names do not conflict with those that are used by Git itself and\n other popular tools, and describe them in your documentation.\nand grew from there.\n\nI don't expect this to be adopted as is, but I've found it much easier\nto discuss something concrete rather than an abstract \"this is\nincomplete\" or \"this is hard to find.\"\n\nCut from master.\n\nkeni (6):\n Tell the glossary about core.hooksPath\n Add bit on extending git to Hacking Git\n Add namespace collision avoidance guidelines file\n Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt\n Tell config.txt about NAMESPACE COLLISIONS\n Add NAMESPACE COLLISIONS reference to Hacking Git\n\n Documentation/config.txt | 4 +-\n Documentation/gitrepository-layout.txt | 2 +\n Documentation/glossary-content.txt | 10 ++-\n .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n Documentation/user-manual.txt | 9 ++\n 5 files changed, 106 insertions(+), 5 deletions(-)\n create mode 100644 Documentation/technical/namespace-collisions.txt\n\n-- \n2.17.1\n\n"},{"id":"397998","messageId":"1589681624-36969-7-git-send-email-keni@hers.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH 6/6] Add NAMESPACE COLLISIONS reference to Hacking Git","fromName":"Kenneth Lorber","fromEmail":"keni@hers.com","sentAt":"2020-05-17T02:13:44Z","receivedAt":"2020-05-17T02:29:21Z","isPatch":true,"sender":{"key":"keni@hers.com","avatar":null},"body":"From: Kenneth Lorber \n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/user-manual.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 2144246444..4ceba4a943 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4056,6 +4056,7 @@ documents may be what you are really looking for:\n * hooks: linkgit:githooks[5]\n * attributes: linkgit:gitattributes[5]\n * new tools: linkgit:git-sh-setup[1]\n+* avoiding namespace collisions: linkgit:gitrepository-layout[5]\n \n [[object-details]]\n === Object storage format\n-- \n2.17.1\n\n"},{"id":"398004","messageId":"20200517074258.GA1381@Abhishek-Arch","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 0/6] various documentation bits","fromName":"Abhishek Kumar","fromEmail":"abhishekkumar8222@gmail.com","sentAt":"2020-05-17T07:42:58Z","receivedAt":"2020-05-17T07:44:41Z","isPatch":true,"sender":{"key":"abhishekkumar8222@gmail.com","avatar":"https://avatars.githubusercontent.com/u/31231064?v=4"},"body":"Hello Kenneth,\n\nOn Sat, May 16, 2020 at 10:13:38PM -0400, Kenneth Lorber wrote:\n> From: Kenneth Lorber \n> \n> This started as an effort to understand this section of config.txt:\n> When inventing new variables for use in your own tool, make sure their\n> names do not conflict with those that are used by Git itself and\n> other popular tools, and describe them in your documentation.\n> and grew from there.\n> \n> I don't expect this to be adopted as is, but I've found it much easier\n> to discuss something concrete rather than an abstract \"this is\n> incomplete\" or \"this is hard to find.\"\n> \n> Cut from master.\n> \n> keni (6):\n> Tell the glossary about core.hooksPath\n> Add bit on extending git to Hacking Git\n> Add namespace collision avoidance guidelines file\n> Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt\n> Tell config.txt about NAMESPACE COLLISIONS\n> Add NAMESPACE COLLISIONS reference to Hacking Git\n> \n> Documentation/config.txt | 4 +-\n> Documentation/gitrepository-layout.txt | 2 +\n> Documentation/glossary-content.txt | 10 ++-\n> .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n> Documentation/user-manual.txt | 9 ++\n> 5 files changed, 106 insertions(+), 5 deletions(-)\n> create mode 100644 Documentation/technical/namespace-collisions.txt\n> \n> -- \n> 2.17.1\n> \n\nSome general notes about your patch series:\n\n1. Conventionally, we prefix the first line with \"area: \" where the area\nis a filename or identifier for general area of the code being modified.\nIt's customary to start the remainder of the first line after \"area: \"\nwith a lower-case letter.\n\nFor example, your commit titles could have been:\n- doc: tell the glossary about core.hooksPath\n- doc: add bit on extending git to hacking Git\n\nand so on.\n\nCheck out SubmittingPatches for more information.\n\n2. We generally don't have a line like in our patches:\n\n> From Kenneth Lorber \n\nBetween the author information and the signed-off-by, it's redundant.\n\n3. You could probably join the patches 3 to 6 together. Or maybe\nintroduce namespace-collisions.txt in third patch and add references in\nall other files in a new, fourth patch.\n\nThanks for the contribution!\n\nRegards\nAbhishek\n"},{"id":"398006","messageId":"20200517094513.GA947@Abhishek-Arch","threadId":"53489","inReplyTo":"1589681624-36969-4-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 3/6] Add namespace collision avoidance guidelines file","fromName":"Abhishek Kumar","fromEmail":"abhishekkumar8222@gmail.com","sentAt":"2020-05-17T09:45:13Z","receivedAt":"2020-05-17T09:46:54Z","isPatch":true,"sender":{"key":"abhishekkumar8222@gmail.com","avatar":"https://avatars.githubusercontent.com/u/31231064?v=4"},"body":"Hello Kenneth,\n\nOn Sat, May 16, 2020 at 10:13:41PM -0400, Kenneth Lorber wrote:\n> From: Kenneth Lorber \n> \n> Add a file of guidelines to prevent the namespace collisions\n> mentioned in git help config without any guidance.\n> \n> Signed-off-by: Kenneth Lorber \n> ---\n\nSince most users (including me) have never faced a namespace collision\nwith Git before, you might have to make a stronger case for why this\nadding namespace collisions to documentation is important.\n\nI honestly don't have enough knowledge of Git internals to talk about\nany changes to the guidelines itself.\n\n> Documentation/gitrepository-layout.txt | 1 +\n> .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n> 2 files changed, 87 insertions(+)\n> create mode 100644 Documentation/technical/namespace-collisions.txt\n> \n> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n> index 1a2ef4c150..a84a4df513 100644\n> --- a/Documentation/gitrepository-layout.txt\n> +++ b/Documentation/gitrepository-layout.txt\n> @@ -290,6 +290,7 @@ worktrees//locked::\n> worktrees//config.worktree::\n> \tWorking directory specific configuration file.\n> \n> +include::technical/namespace-collisions.txt[]\n> include::technical/repository-version.txt[]\n> \n> SEE ALSO\n> diff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt\n> new file mode 100644\n> index 0000000000..fb79c82a73\n> --- /dev/null\n> +++ b/Documentation/technical/namespace-collisions.txt\n> @@ -0,0 +1,86 @@\n> +gitattributes\n> +\n> +\n> +NAMESPACE COLLISIONS\n> +--------------------\n\nA convention I have noticed is that \"========\" is for the document\nheader and \"--------\" is for section headers.\n\n> +Git uses identifiers in a number of different namespaces:\n> +\n> +* environment variables\n> +* files in $GIT_DIR\n> +* files in the working trees\n> +* config sections\n> +* hooks\n> +* attributes\n> +\n> +In order to reduce the chance of collisions between names Git uses\n> +and those used by other entities (users, groups, and extension authors),\n> +the following are recommended best practices.\n> +\n> +Names reserved to Git:\n> +\n> +* file or directory names ending with `.lock`\n> +* file or directory names starting with `.git`\n> +* filenames in $GIT_DIR\n> +* directory names in $GIT_DIR unless allowed by a rule below\n> +* environment variables starting with `GIT_`\n> +* configuration file sections unless allowed by a rule below\n> +* file or directory names in `$GIT_DIR/hooks` unless allowed by a rule below\n> +* attributes unless allowed by a rule below\n> +\n> +\n> +Names reserved for individual users:\n> +\n> +* The directory `$GIT_DIR/my`\n> +* Environment variables starting with `GIT_MY_`\n> +* Configuration section `my`\n> +* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n> +* Attributes starting with `my_`\n> +\n> +Names reserved for individual repos:\n> +\n> +* The directory `$GIT_DIR/this`\n> +* Environment variables starting with `GIT_THIS_`\n> +* Configuration section `this`\n> +* Files or directories in `$GIT_DIR/hooks` starting with `this_`\n> +* Attributes starting with `this_`\n> +\n> +Names reserved for the lowest level group of people:\n> +\n> +* The directory `$GIT_DIR/our`\n> +* Environment variables starting with `GIT_OUR_`\n> +* Configuration section `our`\n> +* Files or directories in `$GIT_DIR/hooks` starting with `our_`\n> +* Attributes starting with `our_`\n> +\n> +Names reserved for larger groups of people, for companies,\n> +or for extensions that are distributed outside of the originating group:\n> +\n> +$ID is defined as a reverse DNS-style name, with dots replaced by\n> +underscores (preferably) or by hyphens (if necessary). The $ID\n> +can have as many sections as possible, thus `com.example.sitename.projectid`\n> +is perfectly reasonable. Use of a name based on a domain you control is\n> +highly recommended; if you do not control a domain, constructing the base of $ID\n> +from your email address is a reasonable alternative, but use double delimiters\n> +in place of the @ sign; for example: `com.example--root.project`\n> +\n> +* The directory $GIT_DIR/$ID\n> +* Environment variables starting with `GIT__$ID_` (note two underscores)\n> +* Configuration section `GIT--$ID`\n> +* Files or directories in `$GIT_DIR/hooks` starting with $ID\n> +* Attributes starting with `git__` (note two underscores)\n> +\n> +Aliases\n> +~~~~~~~\n> +Aliases are a special case. Users need to type them so they should be\n> +short, but there is no way to prevent such short names from colliding.\n> +So the documentation or installer should construct something like:\n> +\n> + [alias]\n> + test = !git my-test\n> + my-test = !echo made it\n> +\n> +while detecting collisions for the short name. Then users or local\n> +policy can deal with collisions on the short name.\n> +\n> +This is not meant to cover every possible use case - a policy that\n> +detailed would be ignored and thus of no use. Please play nicely.\n> -- \n> 2.17.1\n> \n\nRegards\nAbhishek\n"},{"id":"398011","messageId":"xmqqh7we7f4b.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"1589681624-36969-4-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 3/6] Add namespace collision avoidance guidelines file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-17T15:31:00Z","receivedAt":"2020-05-17T15:31:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> From: Kenneth Lorber \n>\n> Add a file of guidelines to prevent the namespace collisions\n> mentioned in git help config without any guidance.\n\nCollisions with whom are you worried about?\n\nRandom $stuff the end users want to have the namespace that governs\n$stuff (where $stuff could be an environment variable, a file on the\nfilesystem, refname in git, etc.)?\n\nRandom $stuff third-party tools want to add?\n\nAs far as git is concerned, all the files under $GIT_DIR are\nblackbox and off-limits from end users and third-party tools, so\nthere is no collisions in \"a file on the filesystem\", but creating a\nref may result in a creation of a file in $GIT_DIR/, and carving out\na part of refs/* hierarchy for use by a third-party tool is a\nworthwhile goal. Just like \"git bisect\" uses refs/bisect/* for its\nown operation and wants to reserve the hierarchy from other tools\nand the end users, any third-party tool would want a similar\ncarve-out. The same for configuration variables.\n\nHOWEVER\n\nI would rather not to see an arbitrary set of rules that are not\nbattle-tested in the field added to our documentation.\n\nInstead, my preference is to add a document that describes what\nnamespaces (e.g. environment variable, reference, configuration\nvarable) third-party tools may want carving out for themselves to\nraise awareness of writers of such tools, and tell them to talk to\nus on the list, saying \"I plan to write a tool that wants to reserve\nrefs/frotz/ hierarchy for its own use---comments?\", so that people\ncan respond with \"I know a tool that already uses that hierarchy, so\nyou'd need to come up with a different one\" to save hassles of\nhaving to rename before it happens.\n\nAfter gaining experience from such exchanges, we might come up a set\nof rules so that no collisions would be possible without any\ncoordination, and then we could document those rules. \n\nI do not think that is plausible to happen, but that is OK.\n"},{"id":"398016","messageId":"xmqq4kse76od.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"1589681624-36969-2-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 1/6] Tell the glossary about core.hooksPath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-17T18:33:22Z","receivedAt":"2020-05-17T18:33:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> From: Kenneth Lorber \n>\n> The user manual glossary entry for hooks now knows about core.hooksPath.\n>\n> Signed-off-by: Kenneth Lorber \n> ---\n> Documentation/glossary-content.txt | 10 ++++++----\n> 1 file changed, 6 insertions(+), 4 deletions(-)\n\nThat's a gap worth filling.\n\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 090c888335..37147db1bc 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -206,10 +206,12 @@ for a more flexible and robust system to do the same thing.\n> \tto optional scripts that allow a developer to add functionality or\n> \tchecking. Typically, the hooks allow for a command to be pre-verified\n> \tand potentially aborted, and allow for a post-notification after the\n> -\toperation is done. The hook scripts are found in the\n> -\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n> -\tremoving the `.sample` suffix from the filename. In earlier versions\n> -\tof Git you had to make them executable.\n> +\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n> +\tor in any directory specified by the `core.hooksPath` configuration\n\nI expect \"the\", instead of \"any\", would make more sense to readers.\n\nIt is true that you can choose any directory of your liking and\nspecify it via the variable, but once chosen that would be the only\ndirectory used for the purpose.\n\n> +\tvariable. The sample scripts are enabled by simply\n> +\tremoving the `.sample` suffix from the filename. In earlier versions\n> +\tof Git you had to make the sample scripts executable manually.\n> +\tHook scripts must be executable. See linkgit:githooks[5] for details.\n> \n> [[def_index]]index::\n> \tA collection of files with stat information, whose contents are stored\n\nThanks.\n"},{"id":"398017","messageId":"xmqqzha65s1l.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"1589681624-36969-3-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 2/6] Add bit on extending git to Hacking Git","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-17T18:34:46Z","receivedAt":"2020-05-17T18:35:21Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> From: Kenneth Lorber \n>\n> The Hacking Git section of the user manual is the logical place to look\n> for information on extending Gut, so add a short section of links to\n> places where that information actually lives.\n>\n> Signed-off-by: Kenneth Lorber \n> ---\n> Documentation/user-manual.txt | 8 ++++++++\n> 1 file changed, 8 insertions(+)\n>\n> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n> index 833652983f..2144246444 100644\n> --- a/Documentation/user-manual.txt\n> +++ b/Documentation/user-manual.txt\n> @@ -4049,6 +4049,14 @@ and that is what higher level `git merge -s resolve` is implemented with.\n> This chapter covers internal details of the Git implementation which\n> probably only Git developers need to understand.\n> \n> +If you are extending Git using hooks, writing new tools, or otherwise\n> +looking for technical information but not hacking Git itself, the following\n> +documents may be what you are really looking for:\n> +\n> +* hooks: linkgit:githooks[5]\n> +* attributes: linkgit:gitattributes[5]\n> +* new tools: linkgit:git-sh-setup[1]\n\nI am not sure if this fits here. It is a distraction to the target\naudience of this section, no?\n"},{"id":"398018","messageId":"xmqqv9ku5rsw.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"20200517074258.GA1381@Abhishek-Arch","subject":"Re: [RFC PATCH 0/6] various documentation bits","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-17T18:39:59Z","receivedAt":"2020-05-17T18:40:03Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Abhishek Kumar writes:\n\n> Some general notes about your patch series:\n>\n> 1. Conventionally, we prefix the first line with \"area: \" where the area\n> is a filename or identifier for general area of the code being modified.\n> It's customary to start the remainder of the first line after \"area: \"\n> with a lower-case letter.\n>\n> For example, your commit titles could have been:\n> - doc: tell the glossary about core.hooksPath\n> - doc: add bit on extending git to hacking Git\n>\n> and so on.\n>\n> Check out SubmittingPatches for more information.\n\nGood suggestion.\n\n> 2. We generally don't have a line like in our patches:\n>\n>> From Kenneth Lorber \n>\n> Between the author information and the signed-off-by, it's redundant.\n\nCarefully inspect the e-mail header and in-body header ;-) \n\nThe author identity must match the identity written for the\nsigned-off-by trailer, so the in-body header becomes needed\nwhen the From: e-mail header does not match the true author,\nlike these patches.\n\n> 3. You could probably join the patches 3 to 6 together. Or maybe\n> introduce namespace-collisions.txt in third patch and add\n> references in all other files in a new, fourth patch.\n\nPerhaps, but I'd rather not to see a rule that hasn't been applied\neven once in the real situation written down like a law. I'd prefer\nto see us gain experience by interacting tool authors on the list\nand learn what their concerns and pain-points are.\n\nThansk.\n\n\n"},{"id":"398034","messageId":"xmqqr1vi5brm.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"1589681624-36969-5-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 4/6] Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-18T00:26:21Z","receivedAt":"2020-05-18T00:26:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> From: Kenneth Lorber \n>\n> Signed-off-by: Kenneth Lorber \n> ---\n> Documentation/gitrepository-layout.txt | 3 ++-\n> 1 file changed, 2 insertions(+), 1 deletion(-)\n\nAs I said elsewhere, I am not sure if we want to even let\nthird-party tools direct access at the filesystem level to\n$GIT_DIR/. We do want to say things like where the ref namespace\nthat are taken as \"per worktree\" are located, so that a third-party\ntool wants to carve out a hierarchy out of the per-worktree part of\nthe ref namespace, that may indirectly influence where on the\nfilesystem under $GIT_DIR/ their stuff is stored, but how we decide\nto store refs inside $GIT_DIR/ should still be blackbox to these\nthird-party tools (e.g. we may not be using loose or packed refs,\nbut using a chain of reftable files). \n\nSo from that point of view, we shouldn't have to touch the\nrepository layout document, I would think.\n\n> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n> index a84a4df513..8050e8cc1f 100644\n> --- a/Documentation/gitrepository-layout.txt\n> +++ b/Documentation/gitrepository-layout.txt\n> @@ -290,9 +290,10 @@ worktrees//locked::\n> worktrees//config.worktree::\n> \tWorking directory specific configuration file.\n> \n> -include::technical/namespace-collisions.txt[]\n> include::technical/repository-version.txt[]\n> \n> +include::technical/namespace-collisions.txt[]\n> +\n> SEE ALSO\n> --------\n> linkgit:git-init[1],\n"},{"id":"398035","messageId":"xmqqmu665bha.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"1589681624-36969-6-git-send-email-keni@hers.com","subject":"Re: [RFC PATCH 5/6] Tell config.txt about NAMESPACE COLLISIONS","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-18T00:32:33Z","receivedAt":"2020-05-18T00:32:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> From: Kenneth Lorber \n>\n> Add a link to the NAMESPACE COLLISIONS information where git help config\n> only mentioned the issue without supplying any guidance for how to do that.\n>\n> Signed-off-by: Kenneth Lorber \n> ---\n> Documentation/config.txt | 4 +++-\n> 1 file changed, 3 insertions(+), 1 deletion(-)\n>\n> diff --git a/Documentation/config.txt b/Documentation/config.txt\n> index ef0768b91a..1e819c26f0 100644\n> --- a/Documentation/config.txt\n> +++ b/Documentation/config.txt\n> @@ -310,7 +310,9 @@ in the appropriate manual page.\n> Other git-related tools may and do use their own variables. When\n> inventing new variables for use in your own tool, make sure their\n> names do not conflict with those that are used by Git itself and\n> -other popular tools, and describe them in your documentation.\n> +other popular tools, and describe them in your documentation. See\n> +'NAMESPACE COLLISIONS' in linkgit:gitrepository-layout[5] for guidelines\n> +to prevent such conflicts.\n\nThe configuration variable namespace is a shared resource, and it\ndoes make sense to give a provision for third-party tools to\ncoordinate to avoid stepping on each others' toes.\n\nThe repository-layout document is about a physical on-filesystem\nstructure that ought to be blackbox to third-party tools, so the\nlink target may have to be different from what this patch wants to\nadd, though. \n\nI'd rather not to have such a document prematurely; if we were to\nadd something to this paragraph (and I do think it is a good idea to\nsay a bit more than \"you're on your own but make sure you do not\nconflict with Git and other people\" which is what we have there in\nthe original), I'd just stop at telling readers to come here to the\nlist to discuss and solicit input from other Git stakeholders.\n\nThanks.\n\n"},{"id":"398088","messageId":"E3FDDD1B-E0D9-4F20-8B4A-FCC5933F7093@his.com","threadId":"53489","inReplyTo":"20200517094513.GA947@Abhishek-Arch","subject":"Re: [RFC PATCH 3/6] Add namespace collision avoidance guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T15:51:41Z","receivedAt":"2020-05-18T15:51:45Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 5:45 AM, Abhishek Kumar wrote:\n> \n> Hello Kenneth,\n> \n> On Sat, May 16, 2020 at 10:13:41PM -0400, Kenneth Lorber wrote:\n>> From: Kenneth Lorber \n>> \n>> Add a file of guidelines to prevent the namespace collisions\n>> mentioned in git help config without any guidance.\n>> \n>> Signed-off-by: Kenneth Lorber \n>> ---\n> \n> Since most users (including me) have never faced a namespace collision\n> with Git before, you might have to make a stronger case for why this\n> adding namespace collisions to documentation is important.\n\n(This will be addressed in a followup email to a reply later in my inbox.)\n\n> \n> I honestly don't have enough knowledge of Git internals to talk about\n> any changes to the guidelines itself.\n\nFair enough.\n\n> \n>> Documentation/gitrepository-layout.txt | 1 +\n>> .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n>> 2 files changed, 87 insertions(+)\n>> create mode 100644 Documentation/technical/namespace-collisions.txt\n>> \n>> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n>> index 1a2ef4c150..a84a4df513 100644\n>> --- a/Documentation/gitrepository-layout.txt\n>> +++ b/Documentation/gitrepository-layout.txt\n>> @@ -290,6 +290,7 @@ worktrees//locked::\n>> worktrees//config.worktree::\n>> \tWorking directory specific configuration file.\n>> \n>> +include::technical/namespace-collisions.txt[]\n>> include::technical/repository-version.txt[]\n>> \n>> SEE ALSO\n>> diff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt\n>> new file mode 100644\n>> index 0000000000..fb79c82a73\n>> --- /dev/null\n>> +++ b/Documentation/technical/namespace-collisions.txt\n>> @@ -0,0 +1,86 @@\n>> +gitattributes\n>> +\n>> +\n>> +NAMESPACE COLLISIONS\n>> +--------------------\n> \n> A convention I have noticed is that \"========\" is for the document\n> header and \"--------\" is for section headers.\n\nAt the moment at least this is not a stand-alone document, it is included\nas a section in gitrepository-layout.txt. (See patch 4.) It's a separate\nfile because I thought it likely someone would suggest putting the content\nelsewhere or, as you seem to have assumed, it could be a stand-alone document.\n\n> \n>> +Git uses identifiers in a number of different namespaces:\n>> +\n>> +* environment variables\n>> +* files in $GIT_DIR\n>> +* files in the working trees\n>> +* config sections\n>> +* hooks\n>> +* attributes\n>> +\n>> +In order to reduce the chance of collisions between names Git uses\n>> +and those used by other entities (users, groups, and extension authors),\n>> +the following are recommended best practices.\n>> +\n>> +Names reserved to Git:\n>> +\n>> +* file or directory names ending with `.lock`\n>> +* file or directory names starting with `.git`\n>> +* filenames in $GIT_DIR\n>> +* directory names in $GIT_DIR unless allowed by a rule below\n>> +* environment variables starting with `GIT_`\n>> +* configuration file sections unless allowed by a rule below\n>> +* file or directory names in `$GIT_DIR/hooks` unless allowed by a rule below\n>> +* attributes unless allowed by a rule below\n>> +\n>> +\n>> +Names reserved for individual users:\n>> +\n>> +* The directory `$GIT_DIR/my`\n>> +* Environment variables starting with `GIT_MY_`\n>> +* Configuration section `my`\n>> +* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n>> +* Attributes starting with `my_`\n>> +\n>> +Names reserved for individual repos:\n>> +\n>> +* The directory `$GIT_DIR/this`\n>> +* Environment variables starting with `GIT_THIS_`\n>> +* Configuration section `this`\n>> +* Files or directories in `$GIT_DIR/hooks` starting with `this_`\n>> +* Attributes starting with `this_`\n>> +\n>> +Names reserved for the lowest level group of people:\n>> +\n>> +* The directory `$GIT_DIR/our`\n>> +* Environment variables starting with `GIT_OUR_`\n>> +* Configuration section `our`\n>> +* Files or directories in `$GIT_DIR/hooks` starting with `our_`\n>> +* Attributes starting with `our_`\n>> +\n>> +Names reserved for larger groups of people, for companies,\n>> +or for extensions that are distributed outside of the originating group:\n>> +\n>> +$ID is defined as a reverse DNS-style name, with dots replaced by\n>> +underscores (preferably) or by hyphens (if necessary). The $ID\n>> +can have as many sections as possible, thus `com.example.sitename.projectid`\n>> +is perfectly reasonable. Use of a name based on a domain you control is\n>> +highly recommended; if you do not control a domain, constructing the base of $ID\n>> +from your email address is a reasonable alternative, but use double delimiters\n>> +in place of the @ sign; for example: `com.example--root.project`\n>> +\n>> +* The directory $GIT_DIR/$ID\n>> +* Environment variables starting with `GIT__$ID_` (note two underscores)\n>> +* Configuration section `GIT--$ID`\n>> +* Files or directories in `$GIT_DIR/hooks` starting with $ID\n>> +* Attributes starting with `git__` (note two underscores)\n>> +\n>> +Aliases\n>> +~~~~~~~\n>> +Aliases are a special case. Users need to type them so they should be\n>> +short, but there is no way to prevent such short names from colliding.\n>> +So the documentation or installer should construct something like:\n>> +\n>> + [alias]\n>> + test = !git my-test\n>> + my-test = !echo made it\n>> +\n>> +while detecting collisions for the short name. Then users or local\n>> +policy can deal with collisions on the short name.\n>> +\n>> +This is not meant to cover every possible use case - a policy that\n>> +detailed would be ignored and thus of no use. Please play nicely.\n>> -- \n>> 2.17.1\n>> \n> \n> Regards\n> Abhishek\n\nThanks,\nKeni\n\n"},{"id":"398089","messageId":"617F5EC4-2C1F-48D7-88CC-48B18D26142A@his.com","threadId":"53489","inReplyTo":"20200517074258.GA1381@Abhishek-Arch","subject":"Re: [RFC PATCH 0/6] various documentation bits","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T15:45:55Z","receivedAt":"2020-05-18T15:54:54Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 3:42 AM, Abhishek Kumar wrote:\n> \n> Hello Kenneth,\n\nHello. Thanks for taking the time to assist me. I am gradually working through all the replies.\n\n> \n> On Sat, May 16, 2020 at 10:13:38PM -0400, Kenneth Lorber wrote:\n>> From: Kenneth Lorber \n>> \n>> This started as an effort to understand this section of config.txt:\n>> When inventing new variables for use in your own tool, make sure their\n>> names do not conflict with those that are used by Git itself and\n>> other popular tools, and describe them in your documentation.\n>> and grew from there.\n>> \n>> I don't expect this to be adopted as is, but I've found it much easier\n>> to discuss something concrete rather than an abstract \"this is\n>> incomplete\" or \"this is hard to find.\"\n>> \n>> Cut from master.\n>> \n>> keni (6):\n>> Tell the glossary about core.hooksPath\n>> Add bit on extending git to Hacking Git\n>> Add namespace collision avoidance guidelines file\n>> Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt\n>> Tell config.txt about NAMESPACE COLLISIONS\n>> Add NAMESPACE COLLISIONS reference to Hacking Git\n>> \n>> Documentation/config.txt | 4 +-\n>> Documentation/gitrepository-layout.txt | 2 +\n>> Documentation/glossary-content.txt | 10 ++-\n>> .../technical/namespace-collisions.txt | 86 +++++++++++++++++++\n>> Documentation/user-manual.txt | 9 ++\n>> 5 files changed, 106 insertions(+), 5 deletions(-)\n>> create mode 100644 Documentation/technical/namespace-collisions.txt\n>> \n>> -- \n>> 2.17.1\n>> \n> \n> Some general notes about your patch series:\n> \n> 1. Conventionally, we prefix the first line with \"area: \" where the area\n> is a filename or identifier for general area of the code being modified.\n> It's customary to start the remainder of the first line after \"area: \"\n> with a lower-case letter.\n> \n> For example, your commit titles could have been:\n> - doc: tell the glossary about core.hooksPath\n> - doc: add bit on extending git to hacking Git\n> \n> and so on.\n> \n> Check out SubmittingPatches for more information.\n\nGot it. I was working from MyFirstContribution.txt which says only:\n\"Start the commit with a 50-column or less subject line, including the name of the\ncomponent you're working on\". If this is a common mistake, perhaps I should take a\nshot at expanding this a bit?\n\n> \n> 2. We generally don't have a line like in our patches:\n> \n>> From Kenneth Lorber \n\nThat's odd. It's not in the raw 0000-cover-letter.patch file. In response to a comment\nin another email I've been tweaking both config sendemail.* and my system mailer config\nand I can't reproduce it (although I see it in a test message from a couple days ago).\nHopefully that means it's fixed.\n\n> \n> Between the author information and the signed-off-by, it's redundant.\n> \n> 3. You could probably join the patches 3 to 6 together. Or maybe\n> introduce namespace-collisions.txt in third patch and add references in\n> all other files in a new, fourth patch.\n\nI split it out because 6 deepends on 3, but also conflicts with 2 if 3 is rejected.\nI have no objections to this change once the dust settles but I'd prefer not to\nreorganize things until then. If you feel strongly the other way I'll change it now.\n\n> \n> Thanks for the contribution!\n\nYou're welcome.\n\n> \n> Regards\n> Abhishek\n\n"},{"id":"398157","messageId":"19B52AC4-E3E0-4BA4-A383-8EA34681E9B6@his.com","threadId":"53489","inReplyTo":"xmqqh7we7f4b.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH 3/6] Add namespace collision avoidance guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T21:46:10Z","receivedAt":"2020-05-18T21:46:15Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 11:31 AM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> From: Kenneth Lorber \n>> \n>> Add a file of guidelines to prevent the namespace collisions\n>> mentioned in git help config without any guidance.\n> \n> Collisions with whom are you worried about?\n\nThis patch came about when I went to split config for a server's repo into a static part and a dynamic part. The static part goes in a configuration repo (where it gets updated and pushed to production) while the dynamic part is written by the various git commands (and includes the static part). Several things came to mind:\n- config doesn't have an extension, so adding a new name with the same extension doesn't work\n- what files will the current git version put into .git? I don't know.\n- how can I avoid picking names that will show up in future versions of git?\n\nSo the first answer is: collisions with git.\n\nWe also give our developers git extensions to help with our work flow. Some are aliases and some are\nhook scripts, with all the code living in .git/hooks (because that seemed the safest place); if git\nadds a new hook and I'm unlucky, all kinds of breakage are possible.\n\nSo the second answer is: collisions with organization or group extensions.\n\nThe third answer is theoretical: what happens if someone brings in a new git extension that collides with any of the above?\n\n> Random $stuff the end users want to have the namespace that governs\n> $stuff (where $stuff could be an environment variable, a file on the\n> filesystem, refname in git, etc.)?\n> \n> Random $stuff third-party tools want to add?\n> \n> As far as git is concerned, all the files under $GIT_DIR are\n> blackbox and off-limits from end users\n\nWhere does it say that? I see this in the user manual: \"cat .git/HEAD\" so the user manual doesn't seem to press that point.\nJust looking for \".git\" also shows:\n\"you may instead put them in a file in your repository named `.git/info/exclude`\"\n\"touch proj.git/git-daemon-export-ok\"\n\"$ cat >> .git/config < and third-party tools, so\n> there is no collisions in \"a file on the filesystem\", but creating a\n> ref may result in a creation of a file in $GIT_DIR/,\n\nI wasn't aware of that, thanks. It also demonstrates the need to say more about this topic in the docs since I thought I had found all the conflict sources. (Got it - git help revisions, \"1. If $GIT_DIR/ exists, that is what you mean\").\n\nAnd here's a real (if contrived) oddity:\n$ git init\n$ echo a > file1\n$ git add file1\n$ git commit -m xx\n$ echo b >> file1\n$ git commit -F .git/HEAD file1\n$ git reflog COMMIT_EDITMSG\n6fd4d85 COMMIT_EDITMSG@{0}: commit: ref: refs/heads/master\n213ef7d COMMIT_EDITMSG@{1}: commit (initial): xx\n\n> and carving out\n> a part of refs/* hierarchy for use by a third-party tool is a\n> worthwhile goal. Just like \"git bisect\" uses refs/bisect/* for its\n> own operation and wants to reserve the hierarchy from other tools\n> and the end users, any third-party tool would want a similar\n> carve-out. The same for configuration variables.\n> \n> HOWEVER\n> \n> I would rather not to see an arbitrary set of rules that are not\n> battle-tested in the field added to our documentation.\n\nI can't fault that, but I'd like to see more than what's there.\n\n> \n> Instead, my preference is to add a document that describes what\n> namespaces (e.g. environment variable, reference, configuration\n> varable) third-party tools may want carving out for themselves to\n> raise awareness of writers of such tools, and tell them to talk to\n> us on the list, saying \"I plan to write a tool that wants to reserve\n> refs/frotz/ hierarchy for its own use---comments?\", so that people\n> can respond with \"I know a tool that already uses that hierarchy, so\n> you'd need to come up with a different one\" to save hassles of\n> having to rename before it happens.\n\nI don't think that's reasonable. Individual users will not reach out to a mailing list to deal with their personal scripts - they'll just roll the dice. Large corporations or startups in stealth mode may also be unable or unwilling to expose enough of their internal information to get a good recommendation in public.\n\n> \n> After gaining experience from such exchanges, we might come up a set\n> of rules so that no collisions would be possible without any\n> coordination, and then we could document those rules. \n\nWould you be willing to support the \"my\" \"this\" and \"our\" levels while\nreplacing the $ID section with a note for people expecting wide distribution\nof their extension to consult the mailing list?\n\nOr even marking the entire section as \"experimental - this may be updated as we gain experience with real world use; please consult the mailing list...\" ?\n\n> \n> I do not think that is plausible to happen, but that is OK.\n\nI disagree, but then if I agreed I would not have submitted the patch :-)\n\nThanks for you comments,\nKeni\n\n"},{"id":"398158","messageId":"4AD13040-F4F0-402B-A525-A8F2476061AD@his.com","threadId":"53489","inReplyTo":"xmqq4kse76od.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH 1/6] Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T22:06:36Z","receivedAt":"2020-05-18T22:06:41Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 2:33 PM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> From: Kenneth Lorber \n>> \n>> The user manual glossary entry for hooks now knows about core.hooksPath.\n>> \n>> Signed-off-by: Kenneth Lorber \n>> ---\n>> Documentation/glossary-content.txt | 10 ++++++----\n>> 1 file changed, 6 insertions(+), 4 deletions(-)\n> \n> That's a gap worth filling.\n\nThanks.\n\n> \n>> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n>> index 090c888335..37147db1bc 100644\n>> --- a/Documentation/glossary-content.txt\n>> +++ b/Documentation/glossary-content.txt\n>> @@ -206,10 +206,12 @@ for a more flexible and robust system to do the same thing.\n>> \tto optional scripts that allow a developer to add functionality or\n>> \tchecking. Typically, the hooks allow for a command to be pre-verified\n>> \tand potentially aborted, and allow for a post-notification after the\n>> -\toperation is done. The hook scripts are found in the\n>> -\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n>> -\tremoving the `.sample` suffix from the filename. In earlier versions\n>> -\tof Git you had to make them executable.\n>> +\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n>> +\tor in any directory specified by the `core.hooksPath` configuration\n> \n> I expect \"the\", instead of \"any\", would make more sense to readers.\n\nI agree, but I copied it from user-manual.txt, search for core.excludesFile.\nShould it be changed there as well?\n\n> \n> It is true that you can choose any directory of your liking and\n> specify it via the variable, but once chosen that would be the only\n> directory used for the purpose.\n> \n>> +\tvariable. The sample scripts are enabled by simply\n>> +\tremoving the `.sample` suffix from the filename. In earlier versions\n>> +\tof Git you had to make the sample scripts executable manually.\n>> +\tHook scripts must be executable. See linkgit:githooks[5] for details.\n>> \n>> [[def_index]]index::\n>> \tA collection of files with stat information, whose contents are stored\n> \n> Thanks.\n\nYou're welcome.\n\n"},{"id":"398159","messageId":"07D99191-664E-475C-A9B1-7FE4DB5C2165@his.com","threadId":"53489","inReplyTo":"xmqqzha65s1l.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH 2/6] Add bit on extending git to Hacking Git","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T22:10:00Z","receivedAt":"2020-05-18T22:10:03Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 2:34 PM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> From: Kenneth Lorber \n>> \n>> The Hacking Git section of the user manual is the logical place to look\n>> for information on extending Gut, so add a short section of links to\n>> places where that information actually lives.\n>> \n>> Signed-off-by: Kenneth Lorber \n>> ---\n>> Documentation/user-manual.txt | 8 ++++++++\n>> 1 file changed, 8 insertions(+)\n>> \n>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\n>> index 833652983f..2144246444 100644\n>> --- a/Documentation/user-manual.txt\n>> +++ b/Documentation/user-manual.txt\n>> @@ -4049,6 +4049,14 @@ and that is what higher level `git merge -s resolve` is implemented with.\n>> This chapter covers internal details of the Git implementation which\n>> probably only Git developers need to understand.\n>> \n>> +If you are extending Git using hooks, writing new tools, or otherwise\n>> +looking for technical information but not hacking Git itself, the following\n>> +documents may be what you are really looking for:\n>> +\n>> +* hooks: linkgit:githooks[5]\n>> +* attributes: linkgit:gitattributes[5]\n>> +* new tools: linkgit:git-sh-setup[1]\n> \n> I am not sure if this fits here. It is a distraction to the target\n> audience of this section, no?\n\nI agree and still think this is where it goes (unless we start a new chapter on hacking FOR git, which is more than I can handle at the moment).\n\nMy reasoning is that from the available chapters, this is my best bet (as a new user) for finding this information; pointing them elsewhere isn't that big a distraction (it's at the top and short) and would be a great help for people looking for that kind of info.\n\nMy two cents anyway.\n\n"},{"id":"398167","messageId":"E4B7ABAF-DA2C-4A96-BBCF-4F8F0DB45585@his.com","threadId":"53489","inReplyTo":"xmqqv9ku5rsw.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH 0/6] various documentation bits","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T23:44:24Z","receivedAt":"2020-05-18T23:44:28Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 2:39 PM, Junio C Hamano wrote:\n> \n> Abhishek Kumar writes:\n> \n>> Some general notes about your patch series:\n>> \n>> 1. Conventionally, we prefix the first line with \"area: \" where the area\n>> is a filename or identifier for general area of the code being modified.\n>> It's customary to start the remainder of the first line after \"area: \"\n>> with a lower-case letter.\n>> \n>> For example, your commit titles could have been:\n>> - doc: tell the glossary about core.hooksPath\n>> - doc: add bit on extending git to hacking Git\n>> \n>> and so on.\n>> \n>> Check out SubmittingPatches for more information.\n> \n> Good suggestion.\n> \n>> 2. We generally don't have a line like in our patches:\n>> \n>>> From Kenneth Lorber \n>> \n>> Between the author information and the signed-off-by, it's redundant.\n> \n> Carefully inspect the e-mail header and in-body header ;-) \n> \n> The author identity must match the identity written for the\n> signed-off-by trailer, so the in-body header becomes needed\n> when the From: e-mail header does not match the true author,\n> like these patches.\n\nEmail/git send-email configuration issue. They should match on v2, if I'm lucky.\n\n> \n>> 3. You could probably join the patches 3 to 6 together. Or maybe\n>> introduce namespace-collisions.txt in third patch and add\n>> references in all other files in a new, fourth patch.\n> \n> Perhaps, but I'd rather not to see a rule that hasn't been applied\n> even once in the real situation written down like a law. I'd prefer\n> to see us gain experience by interacting tool authors on the list\n> and learn what their concerns and pain-points are.\n\nThis tool author/git admin went for a patch to discuss.\n\nI assume from the above there has been no interaction before, so at the very least we need a pointer to the list for this topic to cause that interaction to occur.\n\nAs I noted in another part of this thread, we can certainly make it less of a law and more of a recommendation or hint.\n\nI listed some of the issues elsewhere; if that isn't quite what you are looking for I can expand on it.\n\n> \n> Thansk.\n\nThank you,\nKeni\n\n"},{"id":"398168","messageId":"6FA1EDEE-5DB4-446D-9579-593E9EADFC0F@his.com","threadId":"53489","inReplyTo":"xmqqr1vi5brm.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH 4/6] Include NAMESPACE COLLISIONS doc into gitrepository-layout.txt","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-18T23:54:54Z","receivedAt":"2020-05-18T23:55:58Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 17, 2020, at 8:26 PM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> From: Kenneth Lorber \n>> \n>> Signed-off-by: Kenneth Lorber \n>> ---\n>> Documentation/gitrepository-layout.txt | 3 ++-\n>> 1 file changed, 2 insertions(+), 1 deletion(-)\n> \n> As I said elsewhere, I am not sure if we want to even let\n> third-party tools direct access at the filesystem level to\n> $GIT_DIR/. We do want to say things like where the ref namespace\n> that are taken as \"per worktree\" are located, so that a third-party\n> tool wants to carve out a hierarchy out of the per-worktree part of\n> the ref namespace, that may indirectly influence where on the\n> filesystem under $GIT_DIR/ their stuff is stored, but how we decide\n> to store refs inside $GIT_DIR/ should still be blackbox to these\n> third-party tools (e.g. we may not be using loose or packed refs,\n> but using a chain of reftable files). \n\nProbably true in the abstract, but the current situation is an undefined mix. Changing it is almost certainly more work than it's worth (my little game with COMMIT_EDITMSG notwithstanding), but documenting some safe places for end users seems reasonable to me.\n\n> \n> So from that point of view, we shouldn't have to touch the\n> repository layout document, I would think.\n\nWhere the information goes is certainly up for debate - that's why I put it in its own file.\nAny suggestions for a better place?\n\n(It looks like I may not have backed up far enough when I cut this diff. I'll fix that for v2.)\n\n> \n>> diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\n>> index a84a4df513..8050e8cc1f 100644\n>> --- a/Documentation/gitrepository-layout.txt\n>> +++ b/Documentation/gitrepository-layout.txt\n>> @@ -290,9 +290,10 @@ worktrees//locked::\n>> worktrees//config.worktree::\n>> \tWorking directory specific configuration file.\n>> \n>> -include::technical/namespace-collisions.txt[]\n>> include::technical/repository-version.txt[]\n>> \n>> +include::technical/namespace-collisions.txt[]\n>> +\n>> SEE ALSO\n>> --------\n>> linkgit:git-init[1],\n\n"},{"id":"398564","messageId":"20200525232727.21096-7-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 6/6] doc: Add collision reference to Hacking Git","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:27Z","receivedAt":"2020-05-25T23:34:56Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Signed-off-by: Kenneth Lorber \n---\n Documentation/user-manual.txt | 1 +\n 1 file changed, 1 insertion(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 2144246444..4ceba4a943 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4056,6 +4056,7 @@ documents may be what you are really looking for:\n * hooks: linkgit:githooks[5]\n * attributes: linkgit:gitattributes[5]\n * new tools: linkgit:git-sh-setup[1]\n+* avoiding namespace collisions: linkgit:gitrepository-layout[5]\n \n [[object-details]]\n === Object storage format\n-- \n2.17.1\n\n"},{"id":"398565","messageId":"20200525232727.21096-3-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 2/6] doc: Add bit on extending git to Hacking Git","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:23Z","receivedAt":"2020-05-25T23:34:56Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"The Hacking Git section of the user manual is the logical place to look\nfor information on extending Gut, so add a short section of links to\nplaces where that information actually lives.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/user-manual.txt | 8 ++++++++\n 1 file changed, 8 insertions(+)\n\ndiff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt\nindex 833652983f..2144246444 100644\n--- a/Documentation/user-manual.txt\n+++ b/Documentation/user-manual.txt\n@@ -4049,6 +4049,14 @@ and that is what higher level `git merge -s resolve` is implemented with.\n This chapter covers internal details of the Git implementation which\n probably only Git developers need to understand.\n \n+If you are extending Git using hooks, writing new tools, or otherwise\n+looking for technical information but not hacking Git itself, the following\n+documents may be what you are really looking for:\n+\n+* hooks: linkgit:githooks[5]\n+* attributes: linkgit:gitattributes[5]\n+* new tools: linkgit:git-sh-setup[1]\n+\n [[object-details]]\n === Object storage format\n \n-- \n2.17.1\n\n"},{"id":"398566","messageId":"20200525232727.21096-4-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:24Z","receivedAt":"2020-05-25T23:34:58Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Add a file of guidelines to prevent the namespace collisions\nmentioned in git help config without any guidance.\n\nSigned-off-by: Kenneth Lorber \n---\n .../technical/namespace-collisions.txt | 72 +++++++++++++++++++\n 1 file changed, 72 insertions(+)\n create mode 100644 Documentation/technical/namespace-collisions.txt\n\ndiff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt\nnew file mode 100644\nindex 0000000000..2a0cb312c5\n--- /dev/null\n+++ b/Documentation/technical/namespace-collisions.txt\n@@ -0,0 +1,72 @@\n+NAMESPACE COLLISIONS\n+--------------------\n+(Note that the recommendations in this section are under development\n+and subject to change. At this point they should be considered only\n+suggestions. If they do not work for your use case, or you are considering\n+distributing your extension widely, please send a note to the mailing list.)\n+\n+Git uses identifiers in a number of different namespaces:\n+\n+* environment variables\n+* files in $GIT_DIR\n+* files in the working trees\n+* config sections\n+* hooks\n+* attributes\n+\n+In order to reduce the chance of collisions between names Git uses\n+and those used by other entities (users, groups, and extension authors),\n+the following are recommended best practices.\n+\n+\n+Names reserved to Git:\n+\n+* file or directory names ending with `.lock`\n+* file or directory names starting with `.git`\n+* filenames in $GIT_DIR\n+* directory names in $GIT_DIR unless allowed by a rule below\n+* environment variables starting with `GIT_`\n+* configuration file sections unless allowed by a rule below\n+* file or directory names in `$GIT_DIR/hooks` unless allowed by a rule below\n+* attributes unless allowed by a rule below\n+\n+\n+Names reserved for individual users:\n+\n+* The directory `$GIT_DIR/my`\n+* Environment variables starting with `GIT_MY_`\n+* Configuration section `my`\n+* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n+* Attributes starting with `my_`\n+\n+Names reserved for individual repos:\n+\n+* The directory `$GIT_DIR/this`\n+* Environment variables starting with `GIT_THIS_`\n+* Configuration section `this`\n+* Files or directories in `$GIT_DIR/hooks` starting with `this_`\n+* Attributes starting with `this_`\n+\n+Names reserved for the lowest level group of people:\n+\n+* The directory `$GIT_DIR/our`\n+* Environment variables starting with `GIT_OUR_`\n+* Configuration section `our`\n+* Files or directories in `$GIT_DIR/hooks` starting with `our_`\n+* Attributes starting with `our_`\n+\n+Aliases\n+~~~~~~~\n+Aliases are a special case. Users need to type them so they should be\n+short, but there is no way to prevent such short names from colliding.\n+So the documentation or installer should construct something like:\n+\n+ [alias]\n+ test = !git my-test\n+ my-test = !echo made it\n+\n+while detecting collisions for the short name. Then users or local\n+policy can deal with collisions on the short name.\n+\n+This is not meant to cover every possible use case - a policy that\n+detailed would be ignored and thus of no use. Please play nicely.\n-- \n2.17.1\n\n"},{"id":"398567","messageId":"20200525232727.21096-5-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 4/6] doc: Add collision doc to gitrepository-layout.txt","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:25Z","receivedAt":"2020-05-25T23:34:59Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Signed-off-by: Kenneth Lorber \n---\n Documentation/gitrepository-layout.txt | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 1a2ef4c150..8050e8cc1f 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -292,6 +292,8 @@ worktrees//config.worktree::\n \n include::technical/repository-version.txt[]\n \n+include::technical/namespace-collisions.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-init[1],\n-- \n2.17.1\n\n"},{"id":"398568","messageId":"20200525232727.21096-2-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:22Z","receivedAt":"2020-05-25T23:35:00Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"The user manual glossary entry for hooks now knows about core.hooksPath.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/glossary-content.txt | 10 ++++++----\n 1 file changed, 6 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 090c888335..37147db1bc 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -206,10 +206,12 @@ for a more flexible and robust system to do the same thing.\n \tto optional scripts that allow a developer to add functionality or\n \tchecking. Typically, the hooks allow for a command to be pre-verified\n \tand potentially aborted, and allow for a post-notification after the\n-\toperation is done. The hook scripts are found in the\n-\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n-\tremoving the `.sample` suffix from the filename. In earlier versions\n-\tof Git you had to make them executable.\n+\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n+\tor in any directory specified by the `core.hooksPath` configuration\n+\tvariable. The sample scripts are enabled by simply\n+\tremoving the `.sample` suffix from the filename. In earlier versions\n+\tof Git you had to make the sample scripts executable manually.\n+\tHook scripts must be executable. See linkgit:githooks[5] for details.\n \n [[def_index]]index::\n \tA collection of files with stat information, whose contents are stored\n-- \n2.17.1\n\n"},{"id":"398569","messageId":"20200525232727.21096-1-keni@his.com","threadId":"53489","inReplyTo":"1589681624-36969-1-git-send-email-keni@hers.com","subject":"[RFC PATCH v2 0/6] various documentation bits","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:21Z","receivedAt":"2020-05-25T23:35:01Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Major changes since v1:\n- add \"doc:\" prefix to subjects\n- make guidelines file less authoritative; delete $ID concept\nand hopefully fix the conflict between my mailer and my git\nconfiguration which resulted in the extra From: line in the body.\n\nKenneth Lorber (6):\n doc: Tell the glossary about core.hooksPath\n doc: Add bit on extending git to Hacking Git\n doc: Add namespace collision guidelines file\n doc: Add collision doc to gitrepository-layout.txt\n doc: Tell config.txt about namespace collisions\n doc: Add collision reference to Hacking Git\n\n Documentation/config.txt | 4 +-\n Documentation/gitrepository-layout.txt | 2 +\n Documentation/glossary-content.txt | 10 +--\n .../technical/namespace-collisions.txt | 72 +++++++++++++++++++\n Documentation/user-manual.txt | 9 +++\n 5 files changed, 92 insertions(+), 5 deletions(-)\n create mode 100644 Documentation/technical/namespace-collisions.txt\n\n-- \n2.17.1\n\n"},{"id":"398570","messageId":"20200525232727.21096-6-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH v2 5/6] doc: Tell config.txt about namespace collisions","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-25T23:27:26Z","receivedAt":"2020-05-25T23:35:03Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Add a link to the namespace collisions information where git help config\nonly mentioned the issue without supplying any guidance for how to do that.\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/config.txt | 4 +++-\n 1 file changed, 3 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex ef0768b91a..1e819c26f0 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -310,7 +310,9 @@ in the appropriate manual page.\n Other git-related tools may and do use their own variables. When\n inventing new variables for use in your own tool, make sure their\n names do not conflict with those that are used by Git itself and\n-other popular tools, and describe them in your documentation.\n+other popular tools, and describe them in your documentation. See\n+'NAMESPACE COLLISIONS' in linkgit:gitrepository-layout[5] for guidelines\n+to prevent such conflicts.\n \n include::config/advice.txt[]\n \n-- \n2.17.1\n\n"},{"id":"398596","messageId":"xmqqmu5umsjg.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"20200525232727.21096-2-keni@his.com","subject":"Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-26T18:59:15Z","receivedAt":"2020-05-26T18:59:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> Subject: Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath\n\nPerhaps\n\n Subject: [PATCH] glossary: describe core.hooksPath\n\nPlease separate this one patch out and send it again without the\nrest of the series, as this is quite different from the rest of the\n6-patch series and an obvious clarification, unlike the others.\n\n> -\toperation is done. The hook scripts are found in the\n> -\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n> -\tremoving the `.sample` suffix from the filename. In earlier versions\n> -\tof Git you had to make them executable.\n> +\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n\nYou accidentally lost 'the', and because you did an unnecessary\nline-wrapping, such a change became harder to spot. \n\nI am not sure if .sample scripts should be a topioc of this glossary\nentry at all to begin with. And I think it outlived the usefulness\nto describe what was in versions of Git that is more than 10 years\nold. I wonder if it is a better idea to take your new description,\nbut remove everything after \"The sample scripts are enabled...\"\nexcept for the \"see ... for details\" link?\n\n> +\tor in any directory specified by the `core.hooksPath` configuration\n> +\tvariable. The sample scripts are enabled by simply\n> +\tremoving the `.sample` suffix from the filename. In earlier versions\n> +\tof Git you had to make the sample scripts executable manually.\n> +\tHook scripts must be executable. See linkgit:githooks[5] for details.\n\n> [[def_index]]index::\n> \tA collection of files with stat information, whose contents are stored\n"},{"id":"398660","messageId":"79C90EFA-CF65-4AF7-82B2-0B1B6FABA0F8@his.com","threadId":"53489","inReplyTo":"xmqqmu5umsjg.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-27T16:52:25Z","receivedAt":"2020-05-27T16:59:57Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 26, 2020, at 2:59 PM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> Subject: Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath\n> \n> Perhaps\n> \n> Subject: [PATCH] glossary: describe core.hooksPath\n> \n> Please separate this one patch out and send it again without the\n> rest of the series, as this is quite different from the rest of the\n> 6-patch series and an obvious clarification, unlike the others.\n\nWill do.\n\n> \n>> -\toperation is done. The hook scripts are found in the\n>> -\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n>> -\tremoving the `.sample` suffix from the filename. In earlier versions\n>> -\tof Git you had to make them executable.\n>> +\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n> \n> You accidentally lost 'the', and because you did an unnecessary\n> line-wrapping, such a change became harder to spot. \n\nMy apologies.\n\n> \n> I am not sure if .sample scripts should be a topioc of this glossary\n> entry at all to begin with. And I think it outlived the usefulness\n> to describe what was in versions of Git that is more than 10 years\n> old. I wonder if it is a better idea to take your new description,\n> but remove everything after \"The sample scripts are enabled...\"\n> except for the \"see ... for details\" link?\n\nI had considered it but didn't want to presume. If I don't hear any objections\nI will take it out.\n\n> \n>> +\tor in any directory specified by the `core.hooksPath` configuration\n>> +\tvariable. The sample scripts are enabled by simply\n>> +\tremoving the `.sample` suffix from the filename. In earlier versions\n>> +\tof Git you had to make the sample scripts executable manually.\n>> +\tHook scripts must be executable. See linkgit:githooks[5] for details.\n> \n>> [[def_index]]index::\n>> \tA collection of files with stat information, whose contents are stored\n\n"},{"id":"398664","messageId":"79116422-1B77-42E4-BA97-2A0663FF08CB@his.com","threadId":"53489","inReplyTo":"79C90EFA-CF65-4AF7-82B2-0B1B6FABA0F8@his.com","subject":"Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-27T17:18:18Z","receivedAt":"2020-05-27T17:18:21Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 27, 2020, at 12:52 PM, Kenneth Lorber wrote:\n> \n> \n> \n>> On May 26, 2020, at 2:59 PM, Junio C Hamano wrote:\n>> \n>> Kenneth Lorber writes:\n>> \n>>> Subject: Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath\n>> \n>> Perhaps\n>> \n>> Subject: [PATCH] glossary: describe core.hooksPath\n>> \n>> Please separate this one patch out and send it again without the\n>> rest of the series, as this is quite different from the rest of the\n>> 6-patch series and an obvious clarification, unlike the others.\n> \n> Will do.\n> \n>> \n>>> -\toperation is done. The hook scripts are found in the\n>>> -\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n>>> -\tremoving the `.sample` suffix from the filename. In earlier versions\n>>> -\tof Git you had to make them executable.\n>>> +\toperation is done. The hook scripts are found in `$GIT_DIR/hooks/`\n>> \n>> You accidentally lost 'the', and because you did an unnecessary\n>> line-wrapping, such a change became harder to spot. \n> \n> My apologies.\n\nI just read this section a couple more times and I think the dropped \"the\"\nis correct since the sentence structure has changed.\n\nThe sentence in question, unwrapped:\nThe hook scripts are found in `$GIT_DIR/hooks/` or in any directory specified by the `core.hooksPath` configuration variable.\n\nIt might deserve some additional changes though, since the above vaguely implies both locations are checked, which is incorrect. Perhaps this is more accurate:\nThe hook scripts are found in the directory specified by the `core.hooksPath` configuration variable; the default location is `$GIT_DIR/hooks/`.\n\n\n> \n>> \n>> I am not sure if .sample scripts should be a topioc of this glossary\n>> entry at all to begin with. And I think it outlived the usefulness\n>> to describe what was in versions of Git that is more than 10 years\n>> old. I wonder if it is a better idea to take your new description,\n>> but remove everything after \"The sample scripts are enabled...\"\n>> except for the \"see ... for details\" link?\n> \n> I had considered it but didn't want to presume. If I don't hear any objections\n> I will take it out.\n> \n>> \n>>> +\tor in any directory specified by the `core.hooksPath` configuration\n>>> +\tvariable. The sample scripts are enabled by simply\n>>> +\tremoving the `.sample` suffix from the filename. In earlier versions\n>>> +\tof Git you had to make the sample scripts executable manually.\n>>> +\tHook scripts must be executable. See linkgit:githooks[5] for details.\n>> \n>>> [[def_index]]index::\n>>> \tA collection of files with stat information, whose contents are stored\n> \n\n"},{"id":"398665","messageId":"xmqqsgfll2j0.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"79C90EFA-CF65-4AF7-82B2-0B1B6FABA0F8@his.com","subject":"Re: [RFC PATCH v2 1/6] doc: Tell the glossary about core.hooksPath","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-27T17:18:43Z","receivedAt":"2020-05-27T17:18:48Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n>> I am not sure if .sample scripts should be a topioc of this glossary\n>> entry at all to begin with. And I think it outlived the usefulness\n>> to describe what was in versions of Git that is more than 10 years\n>> old. I wonder if it is a better idea to take your new description,\n>> but remove everything after \"The sample scripts are enabled...\"\n>> except for the \"see ... for details\" link?\n>\n> I had considered it but didn't want to presume. If I don't hear any objections\n> I will take it out.\n\nIf it is not too much trouble, it probably is a better organization\nto make this a two-patch series, whose first patch leaves the\noriginal description on .sample files in, and the second patch that\nbuilds on top of the first patch removes the description on .sample\nfiles. That way, if people still likes to see the description on\n.sample, we can just drop the second patch and still use the first\npatch.\n\nThanks.\n"},{"id":"398774","messageId":"xmqqy2pb3new.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"20200525232727.21096-4-keni@his.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-28T18:49:27Z","receivedAt":"2020-05-28T18:49:37Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Kenneth Lorber writes:\n\n> +Git uses identifiers in a number of different namespaces:\n> +\n> +* environment variables\n> +* files in $GIT_DIR\n> +* files in the working trees\n> +* config sections\n> +* hooks\n> +* attributes\n\nThe names of the subcommands \"git\" can spawn is a shared resource.\nYou can install \"git-imerge\" program in one of the directories on\nyour $PATH and say \"git imerge\" to invoke the program. \n\nTwo third-party developers may have to coordinate to avoid giving\nthe same name to their totally-unrelated tools, if they hope that\nboth of their tools to be useful in the larger Git ecosystem.\n\n> +In order to reduce the chance of collisions between names Git uses\n> +and those used by other entities (users, groups, and extension authors),\n> +the following are recommended best practices.\n\nOK.\n\n> +Names reserved to Git:\n\ns/to/by/ perhaps.\n\n> +Names reserved for individual users:\n> +\n> +* The directory `$GIT_DIR/my`\n\nSo an individual user is allowed to store anything in that\ndirectory, and \"git\" or any third-party tools won't care. OK.\n\n> +* Environment variables starting with `GIT_MY_`\n\nLikewise. But then the users can use MY_FOO_BLAH without GIT_\nprefix in the first place, so there isn't much gain there. Downside\nfor \"git\" and third-party tool authors is not so big (just the loss\nof a single prefix \"_MY\"), so perhaps it is OK.\n\n> +* Configuration section `my`\n> +* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n> +* Attributes starting with `my_`\n\nThe last one does not make much sense. You have to forbid defining\nmy_attributes in .gitattributes files that are tracked in-tree;\notherwise I cannot work with you on the same project, because I\ncannot use my_attributes for my own purpose in that project. For\nthe same reason, reserving attributes for individual repositories\ndoes not make much sense, either.\n\n> +Names reserved for individual repos:\n> +\n> +* The directory `$GIT_DIR/this`\n\nIt is unclear what it means to have $GIT_DIR/my and $GIT_DIR/this\nand how to choose which one of these two ought to be used for each\noccasion a user finds a need to store something in these places.\n\n> +* Environment variables starting with `GIT_THIS_`\n\nThe utility of this one is dubious. \n\n\t$ export GIT_THIS_BLAH=value\n\t$ cd repo1 ; work work work\n\t$ cd ../repo2 ; work work work\n\nUnless you arrange to reset GIT_THIS_* environment variable every\ntime you visit a separate repository, it would not be pratical to\nuse.\n\n> +Names reserved for the lowest level group of people:\n\nWhat's lowest level group of people?\n\nAlso, where did the guideline for third-party tools go?\n\nAt this point I need to say that this is not very well thought out\n(yet), or that this is not very well explained, or perhaps both,\nso I'll stop commenting on it for now.\n\nThanks.\n\n\n\n"},{"id":"398781","messageId":"xmqqo8q73lkf.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"xmqqy2pb3new.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-28T19:29:20Z","receivedAt":"2020-05-28T19:29:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Kenneth Lorber writes:\n>\n>> +Git uses identifiers in a number of different namespaces:\n>> +\n>> +* environment variables\n>> +* files in $GIT_DIR\n>> +* files in the working trees\n>> +* config sections\n>> +* hooks\n>> +* attributes\n>\n> The names of the subcommands \"git\" can spawn is a shared resource.\n> You can install \"git-imerge\" program in one of the directories on\n> your $PATH and say \"git imerge\" to invoke the program. \n>\n> Two third-party developers may have to coordinate to avoid giving\n> the same name to their totally-unrelated tools, if they hope that\n> both of their tools to be useful in the larger Git ecosystem.\n\nAlso names of worktrees that are attached to a single repository.\nIf a third-party tool wants to make it \"easy\" for its users by\nautomatically taking a name to do its job (instead of forcing the\nusers to come up with a name and giving it to the tool), the name\nmust be chosen in such a way that it does not collide names in use\nand names the user (or other third-party tools) will pick in the\nfuture.\n\nI (or others) may come up with other things that must be named and\nname collisions must be avoided. Even though I already said that I\ndidn't think the \"suggestions to avoid name collisions\" given by the\nRFC PATCH are well done, I do think it is worth being aware of the\nproblem space, and enumerating what kind of names are shared and\nlimited resource is the first step to become so.\n\nThanks.\n\n\n"},{"id":"398825","messageId":"xmqq7dwv1qqn.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"xmqqo8q73lkf.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-29T01:20:32Z","receivedAt":"2020-05-29T01:20:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n>> The names of the subcommands \"git\" can spawn is a shared resource.\n>> ...\n>\n> Also names of worktrees that are attached to a single repository.\n> ...\n>\n> I (or others) may come up with other things that must be named and\n> name collisions must be avoided. Even though I already said that I\n> didn't think the \"suggestions to avoid name collisions\" given by the\n> RFC PATCH are well done, I do think it is worth being aware of the\n> problem space, and enumerating what kind of names are shared and\n> limited resource is the first step to become so.\n\nHere are a few more.\n\n - The nickname of a remote, like 'origin'.\n - A custom pretty format alias 'pretty.'.\n - Ref hierarchy name (next to refs/{heads,tags,remotes}).\n\nAll of these are defined in the configuration, and unlike\nattributes, they are never defined by in-tree tracked files, so we\ndo not have to worry about \"I use this name, and I want to make sure\nothers do not use the same for different purpose.\" \n\nBut third-party tools may want to carve out a subnamespace for their\nown use, and there needs coordination among them so that they do not\nstomp on each other's toes, or collide with names the end-users\nwould want to use.\n"},{"id":"398897","messageId":"xmqqftbizk99.fsf@gitster.c.googlers.com","threadId":"53489","inReplyTo":"xmqq7dwv1qqn.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-05-29T18:08:50Z","receivedAt":"2020-05-29T18:08:57Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>>> The names of the subcommands \"git\" can spawn is a shared resource.\n>>> ...\n>>\n>> Also names of worktrees that are attached to a single repository.\n>> ...\n>>\n>> I (or others) may come up with other things that must be named and\n>> name collisions must be avoided. Even though I already said that I\n>> didn't think the \"suggestions to avoid name collisions\" given by the\n>> RFC PATCH are well done, I do think it is worth being aware of the\n>> problem space, and enumerating what kind of names are shared and\n>> limited resource is the first step to become so.\n>\n> Here are a few more.\n>\n> - The nickname of a remote, like 'origin'.\n> - A custom pretty format alias 'pretty.'.\n> - Ref hierarchy name (next to refs/{heads,tags,remotes}).\n>\n> All of these are defined in the configuration, and unlike\n> attributes, they are never defined by in-tree tracked files, so we\n> do not have to worry about \"I use this name, and I want to make sure\n> others do not use the same for different purpose.\" \n\nActually \"git fetch --mirror\" would propagate \"private/custom\"\nrefnames used by the other side to anybody, so it does pose \"I use\nthis name, and my use of this name may harm others who may want to\nuse it for other purposes\" issue.\n\n> But third-party tools may want to carve out a subnamespace for their\n> own use, and there needs coordination among them so that they do not\n> stomp on each other's toes, or collide with names the end-users\n> would want to use.\n"},{"id":"398962","messageId":"20200531213757.10752-1-keni@his.com","threadId":"53489","inReplyTo":"20200525232727.21096-1-keni@his.com","subject":"[RFC PATCH 0/2] update glossary hooks entry","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-31T21:37:55Z","receivedAt":"2020-05-31T21:47:40Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Per Junio C Hamano, extract and split\nv2-0001-doc-Tell-the-glossary-about-core.hooksPath.patch\nfrom the series starting with [RFC PATCH v2 0/6] various documentation bits.\n\nKenneth Lorber (2):\n doc: Tell the glossary about core.hooksPath\n doc: remove dated info and refs to sample hooks\n\n Documentation/glossary-content.txt | 8 ++++----\n 1 file changed, 4 insertions(+), 4 deletions(-)\n\n-- \n2.17.1\n\n"},{"id":"398963","messageId":"20200531213757.10752-2-keni@his.com","threadId":"53489","inReplyTo":"20200531213757.10752-1-keni@his.com","subject":"[RFC PATCH 1/2] doc: Tell the glossary about core.hooksPath","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-31T21:37:56Z","receivedAt":"2020-05-31T21:47:40Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"Signed-off-by: Kenneth Lorber \n---\n Documentation/glossary-content.txt | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex 090c888335..a8490830ff 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -206,10 +206,11 @@ for a more flexible and robust system to do the same thing.\n \tto optional scripts that allow a developer to add functionality or\n \tchecking. Typically, the hooks allow for a command to be pre-verified\n \tand potentially aborted, and allow for a post-notification after the\n-\toperation is done. The hook scripts are found in the\n-\t`$GIT_DIR/hooks/` directory, and are enabled by simply\n-\tremoving the `.sample` suffix from the filename. In earlier versions\n-\tof Git you had to make them executable.\n+\toperation is done. The hook scripts are found in\n+\t`$GIT_DIR/hooks/` or in any directory specified by the `core.hooksPath`\n+\tconfiguration variable. The sample scripts are enabled by simply\n+\tremoving the `.sample` suffix from the filename. In earlier versions\n+\tof Git you had to make them executable. See linkgit:githooks[5] for details.\n \n [[def_index]]index::\n \tA collection of files with stat information, whose contents are stored\n-- \n2.17.1\n\n"},{"id":"398964","messageId":"20200531213757.10752-3-keni@his.com","threadId":"53489","inReplyTo":"20200531213757.10752-1-keni@his.com","subject":"[RFC PATCH 2/2] doc: remove dated info and refs to sample hooks","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-05-31T21:37:57Z","receivedAt":"2020-05-31T21:47:40Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"In the glossary entry for hooks:\n- don't discuss renaming the sample hooks\n- don't discuss the need to make the sample hooks executable as the existing\n wording is too specific: it implies only the sample hooks need to be executable\n and the need to make scripts executable is already discussed near the top of hooks(5).\n\nSigned-off-by: Kenneth Lorber \n---\n Documentation/glossary-content.txt | 5 ++---\n 1 file changed, 2 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\nindex a8490830ff..d96b25bef3 100644\n--- a/Documentation/glossary-content.txt\n+++ b/Documentation/glossary-content.txt\n@@ -208,9 +208,8 @@ for a more flexible and robust system to do the same thing.\n \tand potentially aborted, and allow for a post-notification after the\n \toperation is done. The hook scripts are found in\n \t`$GIT_DIR/hooks/` or in any directory specified by the `core.hooksPath`\n-\tconfiguration variable. The sample scripts are enabled by simply\n-\tremoving the `.sample` suffix from the filename. In earlier versions\n-\tof Git you had to make them executable. See linkgit:githooks[5] for details.\n+\tconfiguration variable.\n+\tSee linkgit:githooks[5] for details.\n \n [[def_index]]index::\n \tA collection of files with stat information, whose contents are stored\n-- \n2.17.1\n\n"},{"id":"398985","messageId":"B170FDD5-0B2C-48AB-92F4-223394823754@his.com","threadId":"53489","inReplyTo":"xmqqy2pb3new.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-06-01T18:38:47Z","receivedAt":"2020-06-01T18:47:34Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 28, 2020, at 2:49 PM, Junio C Hamano wrote:\n> \n> Kenneth Lorber writes:\n> \n>> +Git uses identifiers in a number of different namespaces:\n>> +\n>> +* environment variables\n>> +* files in $GIT_DIR\n>> +* files in the working trees\n>> +* config sections\n>> +* hooks\n>> +* attributes\n> \n> The names of the subcommands \"git\" can spawn is a shared resource.\n> You can install \"git-imerge\" program in one of the directories on\n> your $PATH and say \"git imerge\" to invoke the program. \n> \n> Two third-party developers may have to coordinate to avoid giving\n> the same name to their totally-unrelated tools, if they hope that\n> both of their tools to be useful in the larger Git ecosystem.\n\nSo similar to the aliases case.\n\n> \n>> +In order to reduce the chance of collisions between names Git uses\n>> +and those used by other entities (users, groups, and extension authors),\n>> +the following are recommended best practices.\n> \n> OK.\n> \n>> +Names reserved to Git:\n> \n> s/to/by/ perhaps.\n\nI don't believe so. For example, under this proposal, the \"my\" items are\nreserved by Git for the user, while the items in this section are reserved\nto git itself.\n\ns/to/for/ might be clearer?\n\n> \n>> +Names reserved for individual users:\n>> +\n>> +* The directory `$GIT_DIR/my`\n> \n> So an individual user is allowed to store anything in that\n> directory, and \"git\" or any third-party tools won't care. OK.\n> \n>> +* Environment variables starting with `GIT_MY_`\n> \n> Likewise. But then the users can use MY_FOO_BLAH without GIT_\n> prefix in the first place, so there isn't much gain there. Downside\n> for \"git\" and third-party tool authors is not so big (just the loss\n> of a single prefix \"_MY\"), so perhaps it is OK.\n\nThe environment variable namespace is a mess in general; subdividing\nsomething well known (GIT_) seemed safer then hoping for MY to be available.\n\nAlso, and this applies to some of the other cases below, one goal was\nto make the rules as simple and therefore as consistent as possible. So\nwe reserve the same names everywhere we can - little cost, added simplicity.\n\n> \n>> +* Configuration section `my`\n>> +* Files or directories in `$GIT_DIR/hooks` starting with `my_`\n>> +* Attributes starting with `my_`\n> \n> The last one does not make much sense. You have to forbid defining\n> my_attributes in .gitattributes files that are tracked in-tree;\n> otherwise I cannot work with you on the same project, because I\n> cannot use my_attributes for my own purpose in that project.\n\nYes, but they can be useful in $HOME/.config/git/attributes.\n\n> For\n> the same reason, reserving attributes for individual repositories\n> does not make much sense, either.\n\nI may not be following you on this one. What about the use case\nof a filter written specifically for a project-specific\nfile type? That would be a \"this\" attribute so it doesn't collide\nwith anything else.\n\n> \n>> +Names reserved for individual repos:\n>> +\n>> +* The directory `$GIT_DIR/this`\n> \n> It is unclear what it means to have $GIT_DIR/my and $GIT_DIR/this\n> and how to choose which one of these two ought to be used for each\n> occasion a user finds a need to store something in these places.\n\n$GIT_DIR/my would be something a user installs to their local clone\nto do something they want personally (contrived example: it's a good \nplace to put their non-standard editor's temp files so they don't have to\ntouch the shared .gitignore files).\n\n$GIT_DIR/this would be used for things that everyone working on that one\nrepo needs, but only for that one repo.\n\nMore generally, I'm not hoping to guess every possible use case, I'm trying\nto specify a policy that can accommodate all possible use cases - so\ngenerality over specific justifications. \n\n> \n>> +* Environment variables starting with `GIT_THIS_`\n> \n> The utility of this one is dubious. \n> \n> \t$ export GIT_THIS_BLAH=value\n> \t$ cd repo1 ; work work work\n> \t$ cd ../repo2 ; work work work\n> \n> Unless you arrange to reset GIT_THIS_* environment variable every\n> time you visit a separate repository, it would not be pratical to\n> use.\n\nIf you only consider env vars being passed in from the user or shell\ninitialization, I think you are correct. However they could be useful\nfor passing information from one program to another. Passing information\ninto a custom editor invoked from git commit might be a use case.\n\nBut again, being uniform is better than not. \n\n> \n>> +Names reserved for the lowest level group of people:\n> \n> What's lowest level group of people?\n\nPurposefully unspecified, but I can understand if I can't get away with that.\n\nThe lowest level group of people could be two people doing agile development,\neveryone with a particular supervisor, a college class, a family, a department.\nIt's the last chance to be informal, before you either use the third-party\nguidelines or go to the mailing list to ask for help.\n\nWhich brings us to:\n\n> \n> Also, where did the guideline for third-party tools go?\n\nThat was in response to a comment from Abhishek Kumar; it was a\nmistake on my part to take silence from both of you as agreement on my\ncompromise (which involved dropping the third-party section).\n\nI'll put it back if I get enough encouragement to cut a v3.\n\n> \n> At this point I need to say that this is not very well thought out\n> (yet), or that this is not very well explained, or perhaps both,\n> so I'll stop commenting on it for now.\n> \n> Thanks.\n\nYou're welcome. I've got 3 more emails from you to reply to but it may\nnot happen today.\n"},{"id":"399008","messageId":"4654CD5E-6802-4277-AFDE-0DD09A40986B@his.com","threadId":"53489","inReplyTo":"xmqqo8q73lkf.fsf@gitster.c.googlers.com","subject":"Re: [RFC PATCH v2 3/6] doc: Add namespace collision guidelines file","fromName":"Kenneth Lorber","fromEmail":"keni@his.com","sentAt":"2020-06-01T23:55:20Z","receivedAt":"2020-06-01T23:56:24Z","isPatch":true,"sender":{"key":"keni@his.com","avatar":"https://avatars.githubusercontent.com/u/16437442?v=4"},"body":"\n\n> On May 28, 2020, at 3:29 PM, Junio C Hamano wrote:\n> \n> Junio C Hamano writes:\n> \n>> Kenneth Lorber writes:\n>> \n>>> +Git uses identifiers in a number of different namespaces:\n>>> +\n>>> +* environment variables\n>>> +* files in $GIT_DIR\n>>> +* files in the working trees\n>>> +* config sections\n>>> +* hooks\n>>> +* attributes\n>> \n>> The names of the subcommands \"git\" can spawn is a shared resource.\n>> You can install \"git-imerge\" program in one of the directories on\n>> your $PATH and say \"git imerge\" to invoke the program. \n>> \n>> Two third-party developers may have to coordinate to avoid giving\n>> the same name to their totally-unrelated tools, if they hope that\n>> both of their tools to be useful in the larger Git ecosystem.\n> \n> Also names of worktrees that are attached to a single repository.\n> If a third-party tool wants to make it \"easy\" for its users by\n> automatically taking a name to do its job (instead of forcing the\n> users to come up with a name and giving it to the tool), the name\n> must be chosen in such a way that it does not collide names in use\n> and names the user (or other third-party tools) will pick in the\n> future.\n\nOne more, but only as an issue to be documented - you don't need to\nconvince me that trying to handle this should simply be declared\n\"left as an exercise for the reader\" and that's extensions that\nrequire being compiled in to git (so file names, global variables,\nfunctions, test names, etc).\n\nI'd propose \"Do something similar to the above or ask for help on\nthe list\" if that's acceptable (where \"above\" is whatever the current\nproposal turns into).\n\n\n> \n> I (or others) may come up with other things that must be named and\n> name collisions must be avoided. Even though I already said that I\n> didn't think the \"suggestions to avoid name collisions\" given by the\n> RFC PATCH are well done, I do think it is worth being aware of the\n> problem space, and enumerating what kind of names are shared and\n> limited resource is the first step to become so.\n\nEach message seems less enthusiastic than the last. I'm not sure I see any\npoint in creating a v3 until I have time and inspiration to write\nsomething significantly different.\n\n> \n> Thanks.\n\nYou're welcome.\n\nPS - nothing to reply to in the next 2 messages from you. Saved them for v3.\n"}]}