Re: [PATCHv8 4/4] Add documentation for ref namespaces

[Marc Branchaud <marcnarc@xiplink.com>]

On 11-06-07 07:04 PM, Jamey Sharp wrote:
> From: Josh Triplett<josh@joshtriplett.org>
>
> 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).
>
> Commit by Josh Triplett and Jamey Sharp.
>
> Signed-off-by: Josh Triplett<josh@joshtriplett.org>
> Signed-off-by: Jamey Sharp<jamey@minilop.net>
> ---
>   Documentation/Makefile                 |    2 +-
>   Documentation/git-http-backend.txt     |    8 +++
>   Documentation/git-receive-pack.txt     |    2 +-
>   Documentation/git-upload-pack.txt      |    4 ++
>   Documentation/git.txt                  |   13 +++++-
>   Documentation/gitnamespaces.txt        |   75 ++++++++++++++++++++++++++++++++
>   contrib/completion/git-completion.bash |    2 +-
>   7 files changed, 101 insertions(+), 5 deletions(-)
>   create mode 100644 Documentation/gitnamespaces.txt
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 36989b7..2004fbe 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -6,7 +6,7 @@ MAN5_TXT=gitattributes.txt gitignore.txt gitmodules.txt githooks.txt \
>   	gitrepository-layout.txt
>   MAN7_TXT=gitcli.txt gittutorial.txt gittutorial-2.txt \
>   	gitcvs-migration.txt gitcore-tutorial.txt gitglossary.txt \
> -	gitdiffcore.txt gitrevisions.txt gitworkflows.txt
> +	gitdiffcore.txt gitnamespaces.txt gitrevisions.txt gitworkflows.txt
>
>   MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
>   MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT))
> diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt
> index 277d9e1..f4e0741 100644
> --- a/Documentation/git-http-backend.txt
> +++ b/Documentation/git-http-backend.txt
> @@ -119,6 +119,14 @@ ScriptAliasMatch \
>
>   ScriptAlias /git/ /var/www/cgi-bin/gitweb.cgi/
>   ----------------------------------------------------------------
> ++
> +To serve multiple repositories from different linkgit:gitnamespaces[7] in a
> +single repository:
> ++
> +----------------------------------------------------------------
> +SetEnvIf Request_URI "^/git/([^/]*)" GIT_NAMESPACE=$1
> +ScriptAliasMatch ^/git/[^/]*(.*) /usr/libexec/git-core/git-http-backend/storage.git$1
> +----------------------------------------------------------------
>
>   Accelerated static Apache 2.x::
>   	Similar to the above, but Apache can be used to return static
> diff --git a/Documentation/git-receive-pack.txt b/Documentation/git-receive-pack.txt
> index f34e0ae..3534ba0 100644
> --- a/Documentation/git-receive-pack.txt
> +++ b/Documentation/git-receive-pack.txt
> @@ -149,7 +149,7 @@ if the repository is packed and is served via a dumb transport.
>
>   SEE ALSO
>   --------
> -linkgit:git-send-pack[1]
> +linkgit:git-send-pack[1], linkgit:gitnamespaces[7]
>
>   GIT
>   ---
> diff --git a/Documentation/git-upload-pack.txt b/Documentation/git-upload-pack.txt
> index 4c0ca9d..61a9a04 100644
> --- a/Documentation/git-upload-pack.txt
> +++ b/Documentation/git-upload-pack.txt
> @@ -33,6 +33,10 @@ OPTIONS
>   <directory>::
>   	The repository to sync from.
>
> +SEE ALSO
> +--------
> +linkgit:gitnamespaces[7]
> +
>   GIT
>   ---
>   Part of the linkgit:git[1] suite
> diff --git a/Documentation/git.txt b/Documentation/git.txt
> index 5c45446..4cbf741 100644
> --- a/Documentation/git.txt
> +++ b/Documentation/git.txt
> @@ -10,8 +10,8 @@ SYNOPSIS
>   --------
>   [verse]
>   'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
> -    [-p|--paginate|--no-pager] [--no-replace-objects]
> -    [--bare] [--git-dir=<path>] [--work-tree=<path>]
> +    [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
> +    [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
>       [-c<name>=<value>]
>       [--help]<command>  [<args>]
>
> @@ -325,6 +325,11 @@ help ...`.
>   	variable (see core.worktree in linkgit:git-config[1] for a
>   	more detailed discussion).
>
> +--namespace=<path>::
> +	Set the git namespace.  See linkgit:gitnamespaces[7] for more
> +	details.  Equivalent to setting the `GIT_NAMESPACE` environment
> +	variable.
> +
>   --bare::
>   	Treat the repository as a bare repository.  If GIT_DIR
>   	environment is not set, it is set to the current working
> @@ -589,6 +594,10 @@ git so take care if using Cogito etc.
>   	This can also be controlled by the '--work-tree' command line
>   	option and the core.worktree configuration variable.
>
> +'GIT_NAMESPACE'::
> +	Set the git namespace; see linkgit:gitnamespaces[7] for details.
> +	The '--namespace' command-line option also sets this value.
> +

Thanks for this work!

Does --namespace override GIT_NAMESPACE or extend it in some way?

I also have a question about how to use this feature.  We currently have 
a central "Main.git" repo where people put their finished work. 
Developers clone this repo with, say, "git clone 
ssh://host/git/Main.git".  Each developer also has a "personal" repo 
where they can publish work-in-progress branches to share without 
creating churn in Main.git.  Folks add personal repos as remotes in 
their Main.git clone, e.g. "git remote add Marc 
git://host/git/personal/marcnarc/Main.git".

This is a fairly clean model:  The personal repos on the central host 
are just local clones of the Main.git repo, and fetching from a personal 
repo only transmits unique refs.  But setting it up was a bit involved, 
and it looks like namespaces would make things even cleaner on the 
central host.

But I think our users will get tripped up by the remote-ext syntax.  The 
above "remote add" command is reasonably straightforward, but with 
namespaces it would be

	git remote add Marc ext::"git --namespace=personal/marcnarc %s 
git://host/git/Main.git"

I can see a lot of opportunity for confusion as users try to type that in.

So my question is, is there any way we could adopt namespaces without 
teaching our users about remote-ext?  Ideally they would just use the 
same URLs they already use, or maybe a slight variation thereof (e.g. 
git://host/git/Main.git/personal/marcnarc).

		M.