|
| 1 | +gitnamespaces(7) |
| 2 | +================ |
| 3 | + |
| 4 | +NAME |
| 5 | +---- |
| 6 | +gitnamespaces - Git namespaces |
| 7 | + |
| 8 | +DESCRIPTION |
| 9 | +----------- |
| 10 | + |
| 11 | +Git supports dividing the refs of a single repository into multiple |
| 12 | +namespaces, each of which has its own branches, tags, and HEAD. Git can |
| 13 | +expose each namespace as an independent repository to pull from and push |
| 14 | +to, while sharing the object store, and exposing all the refs to |
| 15 | +operations such as linkgit:git-gc[1]. |
| 16 | + |
| 17 | +Storing multiple repositories as namespaces of a single repository |
| 18 | +avoids storing duplicate copies of the same objects, such as when |
| 19 | +storing multiple branches of the same source. The alternates mechanism |
| 20 | +provides similar support for avoiding duplicates, but alternates do not |
| 21 | +prevent duplication between new objects added to the repositories |
| 22 | +without ongoing maintenance, while namespaces do. |
| 23 | + |
| 24 | +To specify a namespace, set the `GIT_NAMESPACE` environment variable to |
| 25 | +the namespace. For each ref namespace, git stores the corresponding |
| 26 | +refs in a directory under `refs/namespaces/`. For example, |
| 27 | +`GIT_NAMESPACE=foo` will store refs under `refs/namespaces/foo/`. You |
| 28 | +can also specify namespaces via the `--namespace` option to |
| 29 | +linkgit:git[1]. |
| 30 | + |
| 31 | +Note that namespaces which include a `/` will expand to a hierarchy of |
| 32 | +namespaces; for example, `GIT_NAMESPACE=foo/bar` will store refs under |
| 33 | +`refs/namespaces/foo/refs/namespaces/bar/`. This makes paths in |
| 34 | +`GIT_NAMESPACE` behave hierarchically, so that cloning with |
| 35 | +`GIT_NAMESPACE=foo/bar` produces the same result as cloning with |
| 36 | +`GIT_NAMESPACE=foo` and cloning from that repo with `GIT_NAMESPACE=bar`. It |
| 37 | +also avoids ambiguity with strange namespace paths such as `foo/refs/heads/`, |
| 38 | +which could otherwise generate directory/file conflicts within the `refs` |
| 39 | +directory. |
| 40 | + |
| 41 | +linkgit:git-upload-pack[1] and linkgit:git-receive-pack[1] rewrite the |
| 42 | +names of refs as specified by `GIT_NAMESPACE`. git-upload-pack and |
| 43 | +git-receive-pack will ignore all references outside the specified |
| 44 | +namespace. |
| 45 | + |
| 46 | +The smart HTTP server, linkgit:git-http-backend[1], will pass |
| 47 | +GIT_NAMESPACE through to the backend programs; see |
| 48 | +linkgit:git-http-backend[1] for sample configuration to expose |
| 49 | +repository namespaces as repositories. |
| 50 | + |
| 51 | +For a simple local test, you can use linkgit:git-remote-ext[1]: |
| 52 | + |
| 53 | +---------- |
| 54 | +git clone ext::'git --namespace=foo %s /tmp/prefixed.git' |
| 55 | +---------- |
| 56 | + |
| 57 | +SECURITY |
| 58 | +-------- |
| 59 | + |
| 60 | +Anyone with access to any namespace within a repository can potentially |
| 61 | +access objects from any other namespace stored in the same repository. |
| 62 | +You can't directly say "give me object ABCD" if you don't have a ref to |
| 63 | +it, but you can do some other sneaky things like: |
| 64 | + |
| 65 | +. Claiming to push ABCD, at which point the server will optimize out the |
| 66 | + need for you to actually send it. Now you have a ref to ABCD and can |
| 67 | + fetch it (claiming not to have it, of course). |
| 68 | + |
| 69 | +. Requesting other refs, claiming that you have ABCD, at which point the |
| 70 | + server may generate deltas against ABCD. |
| 71 | + |
| 72 | +None of this causes a problem if you only host public repositories, or |
| 73 | +if everyone who may read one namespace may also read everything in every |
| 74 | +other namespace (for instance, if everyone in an organization has read |
| 75 | +permission to every repository). |
0 commit comments