Re: [RFC PATCH 3/6] Add namespace collision avoidance guidelines file

[Kenneth Lorber <keni@his.com>]

> On May 17, 2020, at 11:31 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 
> Kenneth Lorber <keni@hers.com> writes:
> 
>> From: Kenneth Lorber <keni@his.com>
>> 
>> Add a file of guidelines to prevent the namespace collisions
>> mentioned in git help config without any guidance.
> 
> Collisions with whom are you worried about?

This 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:
- config doesn't have an extension, so adding a new name with the same extension doesn't work
- what files will the current git version put into .git?  I don't know.
- how can I avoid picking names that will show up in future versions of git?

So the first answer is: collisions with git.

We also give our developers git extensions to help with our work flow.  Some are aliases and some are
hook scripts, with all the code living in .git/hooks (because that seemed the safest place); if git
adds a new hook and I'm unlucky, all kinds of breakage are possible.

So the second answer is: collisions with organization or group extensions.

The third answer is theoretical: what happens if someone brings in a new git extension that collides with any of the above?

> Random $stuff the end users want to have the namespace that governs
> $stuff (where $stuff could be an environment variable, a file on the
> filesystem, refname in git, etc.)?
> 
> Random $stuff third-party tools want to add?
> 
> As far as git is concerned, all the files under $GIT_DIR are
> blackbox and off-limits from end users

Where 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.
Just looking for ".git" also shows:
"you may instead put them in a file in your repository named `.git/info/exclude`"
"touch proj.git/git-daemon-export-ok"
"$ cat >> .git/config <<EOF" (note that this can cause all sorts of grief since it doesn't lock config)
(etc)

That's not true though, is it?  config needs to be edited for all kinds of things, and while "git config -e" is probably the correct answer, a quick grep under Documentation shows zero hits for "config -e" and at least on place where the user manual says "by editing `.git/config` with a text editor".  The hooks directory is also fair game for both users and extensions.  (There's nothing mentioned about running more than one program from a hook, but that's an ugly bit of code I'm not likely to send out, so I'm going to ignore that conflict.)

> and third-party tools, so
> there is no collisions in "a file on the filesystem", but creating a
> ref may result in a creation of a file in $GIT_DIR/,

I 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/<refname> exists, that is what you mean").

And here's a real (if contrived) oddity:
$ git init
$ echo a > file1
$ git add file1
$ git commit -m xx
$ echo b >> file1
$ git commit -F .git/HEAD file1
$ git reflog COMMIT_EDITMSG
6fd4d85 COMMIT_EDITMSG@{0}: commit: ref: refs/heads/master
213ef7d COMMIT_EDITMSG@{1}: commit (initial): xx

> and carving out
> a part of refs/* hierarchy for use by a third-party tool is a
> worthwhile goal.  Just like "git bisect" uses refs/bisect/* for its
> own operation and wants to reserve the hierarchy from other tools
> and the end users, any third-party tool would want a similar
> carve-out.  The same for configuration variables.
> 
> HOWEVER
> 
> I would rather not to see an arbitrary set of rules that are not
> battle-tested in the field added to our documentation.

I can't fault that, but I'd like to see more than what's there.

> 
> Instead, my preference is to add a document that describes what
> namespaces (e.g. environment variable, reference, configuration
> varable) third-party tools may want carving out for themselves to
> raise awareness of writers of such tools, and tell them to talk to
> us on the list, saying "I plan to write a tool that wants to reserve
> refs/frotz/ hierarchy for its own use---comments?", so that people
> can respond with "I know a tool that already uses that hierarchy, so
> you'd need to come up with a different one" to save hassles of
> having to rename before it happens.

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

> 
> After gaining experience from such exchanges, we might come up a set
> of rules so that no collisions would be possible without any
> coordination, and then we could document those rules.  

Would you be willing to support the "my" "this" and "our" levels while
replacing the $ID section with a note for people expecting wide distribution
of their extension to consult the mailing list?

Or even marking the entire section as "experimental - this may be updated as we gain experience with real world use; please consult the mailing list..." ?

> 
> I do not think that is plausible to happen, but that is OK.

I disagree, but then if I agreed I would not have submitted the patch :-)

Thanks for you comments,
Keni