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