> On May 17, 2020, at 5:45 AM, Abhishek Kumar <abhishekkumar8222@xxxxxxxxx> wrote: > > 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. (This will be addressed in a followup email to a reply later in my inbox.) > > I honestly don't have enough knowledge of Git internals to talk about > any changes to the guidelines itself. Fair enough. > >> 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. At the moment at least this is not a stand-alone document, it is included as a section in gitrepository-layout.txt. (See patch 4.) It's a separate file because I thought it likely someone would suggest putting the content elsewhere or, as you seem to have assumed, it could be a stand-alone document. > >> +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 Thanks, Keni
