= Multiple Repository Support for 0.12 =

This branch adds support for accessing multiple repositories inside one Trac project.

For now, there is support for the Mercurial (`hg`) and Subversion (`direct-svnfs`) type of repositories.

See: 
 - log:sandbox/multirepos
 - log:sandbox/mercurial-plugin-0.12

Checkpoints:
 - r6465: initial "release" of the branch, ''worksforme''
 - r6469: a few bug fixes
 - r7590: current version is quite good ;-)

The approach is quite simple: beyond repository connectors, there's now repository providers (IRepositoryProvider components) which are responsible for make available a list of named repositories. That name can be arbitrary (in particular, it may contain '/' to denote a pseudo-hierarchy) and will be used as a prefix for any repository path.
Actually, a more complete description of the approach can be found in this mail: [googlegroups:trac-users:14ca95377e4a53b5 One trac env for X repositories ?].

If the only repository known is the default one (i.e. the one defined in TracIni, section `[trac] repository_...`), then Trac behaves exactly as before.
But `IRepositoryProvider` components can make other repositories available. In particular, the default `RepositoryManager` itself provides a list of repositories listed in a new `[repositories]` section in TracIni. See r6447 for more details.

== Installation (with mercurial) ==

A current installation procedure which works is the following:

 1. Check out the mercurial plugin:
{{{
svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.12
}}}
 2. build the mercurial plugin.  From within the checked-out directory, build the egg file (it will end up in the dist subdirectory):
{{{
python setup.py bdist_egg
}}}
 3. Check out the multirepos branch:
{{{
svn co http://svn.edgewall.com/repos/trac/sandbox/multirepos
}}}
 4. Install the multirepos version of trac (from within the multirepos directory, as root):
{{{
python setup.py install
}}}
 5. Create your trac environment directory

 6. Copy the mercurial plugin egg file to the <trac-env>/plugins directory

 7. make sure the following is somewhere in <trac-env>/conf/trac.ini, adding all the desired repositories to the [repositories] section:
{{{
[components]
tracext.hg.* = enabled

[repositories]
my_repo_a.dir = <path_to_a_repository>
my_repo_b.dir = <path_to_another_repository>
my_repo_c.dir = <path_to_yet_another_repository>
my_repo_c.type = direct-svnfs

[trac]
repository_dir = <path_to_default_repository>
repository_type = hg
}}}
   Note that when the repository `.type` is not specified, the value of `[trac] repository_type` is used. [[br]]
   In the above example, this means that `my_repo_a` and `my_repo_b` are Mercurial (hg) repositories. [[br]]
   Note also that for now, only the `direct-svnfs` repository type can be used for Subversion repositories,
   as the cached repository used by the other type (`svn`) has not yet been extended to support multiple repositories.
 8. Cross your fingers, and hope it works :)
   [[br]] ''It really should or it's a bug ;-)''

To make links to the non-default repository, just add a slash and the alias name after the revision identifier, for example: "![changeset:cffd9e480266/my_repos_b a changeset]".
The default repository can be one of the explicitly named repositories. 

== TODO ==

 - More [changeset:6448 IRepositoryProvider] components:
   - !HgForestRepositoryProvider, for providing forest repositories and all sub-repositories managed by each forest
     - work-in-progress on http://hg.trbs.net
     - in trac.conf use:
{{{
[hg-forest]
jdk7.dir = /path/to/mercurial/root/forest/repository/jdk7
}}}
   - !HgParentDirRepositoryProvider, for listing all the working copies present in a given folder
     - work-in-progress on http://hg.trbs.net
     - in trac.conf use:
{{{
[hg-parents]
bunch.dir = /path/to/parent/directory/somedir
}}}
   - !SvnParentDirRepositoryProvider, for listing all the Subversion repositories present in a given folder
 - currently, a "default" repository (the one defined in the `[trac]` section) ''needs'' to be defined, otherwise the versioncontrol modules are disabled
 - ~~fix AJAX query in annotate~~
 - IRepositoryProvider must have a way to signal new content, in order to rebuild the repository name cache
 - support the `.url` repository metadata (#1781)
 - small issue: visual glitch in Firefox 2 for the new Rev column, 
   where the changeset icon doesn't align properly to the right 
   (but works fine for every other web browser, including Firefox 3)
 - "normal" feature: it's currently not possible to compare across repositories 
   (the situation is detected, but raises a "not implemented" error). 
   It would be quite useful to be able to do so, and it's doable without much work 
   (only need to compare folders in a backend neutral way, we already do our own diff at the file level)
 - extend to '''cached repositories''', see MultipleRepositorySupport/Cache. [[br]]
   In a first step, the existing cache could be adapted to simply handle more than one repository. [[br]]
   Bonus points if that cache is smart enough to handle multiple scoped repositories without data duplication. [[br]]
   A second (much) more ambitious step would be to generalize the cache so that it can support other (d)vcs.

=== Other Open Points ===

taken from #6665:
> A few comments / questions
> 
> 1. How can I get the name in the ''Repository Index'' to keep the case in the name? It is converted to lower case.

ConfigParser limitation.

> 2. Since you use the init tag as the name to show in the ''Repository Index'', it seems I cannot have a period in the name of the repository as shown.

Also related to the way the the .ini keys are read. It would be possible to look first for the ending `.dir` part and then get the name.

> 3. I get a ''default'' in the ''Repository Index'', as well as that same repository listed in the previous single repository manner. I think that when the multiple repositories are listed, and one of them is the same as the trac repository_dir, it does not need to be listed twice or three times.

Yes, known issue, currently it's not possible to get rid of the "default" repository, specified in `[trac]` (see [#TODO]). What you suggest is that aliases (even aliases for the `[trac] repository_dir`) shouldn't be listed, I think that's acceptable, but there should be an easy way to learn about the defined aliases, maybe they can be listed at the bottom of the toplevel page.

> Other than that, so far this is going to meet my needs quite nicely. Thanks!
Thanks :-) 

=== Known Issues ===
[[TicketQuery(keywords=~multirepos)]]