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> --- 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 +-------------------- +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
