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> --- .../technical/namespace-collisions.txt | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 Documentation/technical/namespace-collisions.txt diff --git a/Documentation/technical/namespace-collisions.txt b/Documentation/technical/namespace-collisions.txt new file mode 100644 index 0000000000..2a0cb312c5 --- /dev/null +++ b/Documentation/technical/namespace-collisions.txt @@ -0,0 +1,72 @@ +NAMESPACE COLLISIONS +-------------------- +(Note that the recommendations in this section are under development +and subject to change. At this point they should be considered only +suggestions. If they do not work for your use case, or you are considering +distributing your extension widely, please send a note to the mailing list.) + +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_` + +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
