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>
Josh Triplett committed
Jul 8, 2011 at 16:14 UTC
d49483f0ca1be0994c4f20fe1804d36a28013676
7 files changed
+101
-5
Documentation/Makefile
+1
-1
@@ -6,7 +6,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
6
gitrepository-layout.txt
7
MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
8
gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
9
- gitdiffcore.txt gitrevisions.txt gitworkflows.txt
9
+ gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
10
11
MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
12
MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
Documentation/git-http-backend.txt
+8
@@ -119,6 +119,14 @@ ScriptAliasMatch \
119
120
ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
121
----------------------------------------------------------------
122
++
123
+To serve multiple repositories from different linkgit:gitnamespaces[7] in a
124
+single repository:
125
++
126
+----------------------------------------------------------------
127
+SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
128
+ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
129
+----------------------------------------------------------------
130
131
Accelerated static Apache 2.x::
132
Similar to the above, but Apache can be used to return static
Documentation/git-receive-pack.txt
+1
-1
@@ -149,7 +149,7 @@ if the repository is packed and is served via a dumb transport.
149
150
SEE ALSO
151
--------
152
-linkgit:git-send-pack[1]
152
+linkgit:git-send-pack[1], linkgit:gitnamespaces[7]
153
154
GIT
155
---
Documentation/git-upload-pack.txt
+4
@@ -33,6 +33,10 @@ OPTIONS
33
<directory>::
34
The repository to sync from.
35
36
+SEE ALSO
37
+--------
38
+linkgit:gitnamespaces[7]
39
+
40
GIT
41
---
42
Part of the linkgit:git[1] suite
Documentation/git.txt
+11
-2
@@ -10,8 +10,8 @@ SYNOPSIS
10
--------
11
[verse]
12
'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
13
- [-p|--paginate|--no-pager] [--no-replace-objects]
14
- [--bare] [--git-dir=<path>] [--work-tree=<path>]
13
+ [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
14
+ [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
15
[-c <name>=<value>]
16
[--help] <command> [<args>]
17
@@ -323,6 +323,11 @@ help ...`.
323
variable (see core.worktree in linkgit:git-config[1] for a
324
more detailed discussion).
325
326
+--namespace=<path>::
327
+ Set the git namespace. See linkgit:gitnamespaces[7] for more
328
+ details. Equivalent to setting the `GIT_NAMESPACE` environment
329
+ variable.
330
+
331
--bare::
332
Treat the repository as a bare repository. If GIT_DIR
333
environment is not set, it is set to the current working
@@ -587,6 +592,10 @@ git so take care if using Cogito etc.
592
This can also be controlled by the '--work-tree' command line
593
option and the core.worktree configuration variable.
594
595
+'GIT_NAMESPACE'::
596
+ Set the git namespace; see linkgit:gitnamespaces[7] for details.
597
+ The '--namespace' command-line option also sets this value.
598
+
599
'GIT_CEILING_DIRECTORIES'::
600
This should be a colon-separated list of absolute paths.
601
If set, it is a list of directories that git should not chdir
Documentation/gitnamespaces.txt
new
+75
@@ -0,0 +1,75 @@
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).
contrib/completion/git-completion.bash
+1
-1
@@ -1468,7 +1468,7 @@ _git_help ()
1468
__gitcomp "$__git_all_commands $(__git_aliases)
1469
attributes cli core-tutorial cvs-migration
1470
diffcore gitk glossary hooks ignore modules
1471
- repository-layout tutorial tutorial-2
1471
+ namespaces repository-layout tutorial tutorial-2
1472
workflows
1473
"
1474
}