diff options
author | Josh Triplett <josh@joshtriplett.org> | 2011-07-08 16:14:10 -0700 |
---|---|---|
committer | Junio C Hamano <gitster@pobox.com> | 2011-07-11 09:35:46 -0700 |
commit | d49483f0ca1be0994c4f20fe1804d36a28013676 (patch) | |
tree | 8a9638b50df38102f794c07fabc7869f40ab0114 /Documentation/gitnamespaces.txt | |
parent | 6b01ecfe22f0b6ccb9665cd8d85d78a381fecffc (diff) | |
download | git-d49483f0ca1be0994c4f20fe1804d36a28013676.tar.gz git-d49483f0ca1be0994c4f20fe1804d36a28013676.tar.xz |
ref namespaces: documentation
Document the namespace mechanism in a new gitnamespaces(7) page.
Reference it from receive-pack and upload-pack.
Document the new --namespace option and GIT_NAMESPACE environment
variable in git(1), and reference gitnamespaces(7).
Add a sample Apache configuration to http-backend(1) to support
namespaced repositories, and reference gitnamespaces(7).
Signed-off-by: Josh Triplett <josh@joshtriplett.org>
Signed-off-by: Jamey Sharp <jamey@minilop.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/gitnamespaces.txt')
-rw-r--r-- | Documentation/gitnamespaces.txt | 75 |
1 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/gitnamespaces.txt b/Documentation/gitnamespaces.txt new file mode 100644 index 000000000..ed8924e85 --- /dev/null +++ b/Documentation/gitnamespaces.txt @@ -0,0 +1,75 @@ +gitnamespaces(7) +================ + +NAME +---- +gitnamespaces - Git namespaces + +DESCRIPTION +----------- + +Git supports dividing the refs of a single repository into multiple +namespaces, each of which has its own branches, tags, and HEAD. Git can +expose each namespace as an independent repository to pull from and push +to, while sharing the object store, and exposing all the refs to +operations such as linkgit:git-gc[1]. + +Storing multiple repositories as namespaces of a single repository +avoids storing duplicate copies of the same objects, such as when +storing multiple branches of the same source. The alternates mechanism +provides similar support for avoiding duplicates, but alternates do not +prevent duplication between new objects added to the repositories +without ongoing maintenance, while namespaces do. + +To specify a namespace, set the `GIT_NAMESPACE` environment variable to +the namespace. For each ref namespace, git stores the corresponding +refs in a directory under `refs/namespaces/`. For example, +`GIT_NAMESPACE=foo` will store refs under `refs/namespaces/foo/`. You +can also specify namespaces via the `--namespace` option to +linkgit:git[1]. + +Note that namespaces which include a `/` will expand to a hierarchy of +namespaces; for example, `GIT_NAMESPACE=foo/bar` will store refs under +`refs/namespaces/foo/refs/namespaces/bar/`. This makes paths in +`GIT_NAMESPACE` behave hierarchically, so that cloning with +`GIT_NAMESPACE=foo/bar` produces the same result as cloning with +`GIT_NAMESPACE=foo` and cloning from that repo with `GIT_NAMESPACE=bar`. It +also avoids ambiguity with strange namespace paths such as `foo/refs/heads/`, +which could otherwise generate directory/file conflicts within the `refs` +directory. + +linkgit:git-upload-pack[1] and linkgit:git-receive-pack[1] rewrite the +names of refs as specified by `GIT_NAMESPACE`. git-upload-pack and +git-receive-pack will ignore all references outside the specified +namespace. + +The smart HTTP server, linkgit:git-http-backend[1], will pass +GIT_NAMESPACE through to the backend programs; see +linkgit:git-http-backend[1] for sample configuration to expose +repository namespaces as repositories. + +For a simple local test, you can use linkgit:git-remote-ext[1]: + +---------- +git clone ext::'git --namespace=foo %s /tmp/prefixed.git' +---------- + +SECURITY +-------- + +Anyone with access to any namespace within a repository can potentially +access objects from any other namespace stored in the same repository. +You can't directly say "give me object ABCD" if you don't have a ref to +it, but you can do some other sneaky things like: + +. Claiming to push ABCD, at which point the server will optimize out the + need for you to actually send it. Now you have a ref to ABCD and can + fetch it (claiming not to have it, of course). + +. Requesting other refs, claiming that you have ABCD, at which point the + server may generate deltas against ABCD. + +None of this causes a problem if you only host public repositories, or +if everyone who may read one namespace may also read everything in every +other namespace (for instance, if everyone in an organization has read +permission to every repository). |