Hello Kenneth, On Sat, May 16, 2020 at 10:13:41PM -0400, Kenneth Lorber wrote: > From: Kenneth Lorber <keni@xxxxxxx> > > Add a file of guidelines to prevent the namespace collisions > mentioned in git help config without any guidance. > > Signed-off-by: Kenneth Lorber <keni@xxxxxxx> > --- Since most users (including me) have never faced a namespace collision with Git before, you might have to make a stronger case for why this adding namespace collisions to documentation is important. I honestly don't have enough knowledge of Git internals to talk about any changes to the guidelines itself. > Documentation/gitrepository-layout.txt | 1 + > .../technical/namespace-collisions.txt | 86 +++++++++++++++++++ > 2 files changed, 87 insertions(+) > create mode 100644 Documentation/technical/namespace-collisions.txt > > diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt > index 1a2ef4c150..a84a4df513 100644 > --- a/Documentation/gitrepository-layout.txt > +++ b/Documentation/gitrepository-layout.txt > @@ -290,6 +290,7 @@ worktrees/<id>/locked:: > worktrees/<id>/config.worktree:: > Working directory specific configuration file. > > +include::technical/namespace-collisions.txt[] > include::technical/repository-version.txt[] > > SEE ALSO > diff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt > new file mode 100644 > index 0000000000..fb79c82a73 > --- /dev/null > +++ b/Documentation/technical/namespace-collisions.txt > @@ -0,0 +1,86 @@ > +gitattributes > + > + > +NAMESPACE COLLISIONS > +-------------------- A convention I have noticed is that "========" is for the document header and "--------" is for section headers. > +Git uses identifiers in a number of different namespaces: > + > +* environment variables > +* files in $GIT_DIR > +* files in the working trees > +* config sections > +* hooks > +* attributes > + > +In order to reduce the chance of collisions between names Git uses > +and those used by other entities (users, groups, and extension authors), > +the following are recommended best practices. > + > +Names reserved to Git: > + > +* file or directory names ending with `.lock` > +* file or directory names starting with `.git` > +* filenames in $GIT_DIR > +* directory names in $GIT_DIR unless allowed by a rule below > +* environment variables starting with `GIT_` > +* configuration file sections unless allowed by a rule below > +* file or directory names in `$GIT_DIR/hooks` unless allowed by a rule below > +* attributes unless allowed by a rule below > + > + > +Names reserved for individual users: > + > +* The directory `$GIT_DIR/my` > +* Environment variables starting with `GIT_MY_` > +* Configuration section `my` > +* Files or directories in `$GIT_DIR/hooks` starting with `my_` > +* Attributes starting with `my_` > + > +Names reserved for individual repos: > + > +* The directory `$GIT_DIR/this` > +* Environment variables starting with `GIT_THIS_` > +* Configuration section `this` > +* Files or directories in `$GIT_DIR/hooks` starting with `this_` > +* Attributes starting with `this_` > + > +Names reserved for the lowest level group of people: > + > +* The directory `$GIT_DIR/our` > +* Environment variables starting with `GIT_OUR_` > +* Configuration section `our` > +* Files or directories in `$GIT_DIR/hooks` starting with `our_` > +* Attributes starting with `our_` > + > +Names reserved for larger groups of people, for companies, > +or for extensions that are distributed outside of the originating group: > + > +$ID is defined as a reverse DNS-style name, with dots replaced by > +underscores (preferably) or by hyphens (if necessary). The $ID > +can have as many sections as possible, thus `com.example.sitename.projectid` > +is perfectly reasonable. Use of a name based on a domain you control is > +highly recommended; if you do not control a domain, constructing the base of $ID > +from your email address is a reasonable alternative, but use double delimiters > +in place of the @ sign; for example: `com.example--root.project` > + > +* The directory $GIT_DIR/$ID > +* Environment variables starting with `GIT__$ID_` (note two underscores) > +* Configuration section `GIT--$ID` > +* Files or directories in `$GIT_DIR/hooks` starting with $ID > +* Attributes starting with `git__` (note two underscores) > + > +Aliases > +~~~~~~~ > +Aliases are a special case. Users need to type them so they should be > +short, but there is no way to prevent such short names from colliding. > +So the documentation or installer should construct something like: > + > + [alias] > + test = !git my-test > + my-test = !echo made it > + > +while detecting collisions for the short name. Then users or local > +policy can deal with collisions on the short name. > + > +This is not meant to cover every possible use case - a policy that > +detailed would be ignored and thus of no use. Please play nicely. > -- > 2.17.1 > Regards Abhishek
