projects / thirdparty / git.git / blame
| 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 | ||
| 235ec243 | 64 | include::transfer-data-leaks.txt[] |