== Extension Point : ''IRepositoryProvider'' ==

||'''Interface'''||''IRepositoryProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IRepositoryProvider 0.12]||
||'''Module'''||''trac.versioncontrol.api''||'''Source'''||[source:trunk/trac/versioncontrol/api.py#/IRepositoryProvider api.py]||

The ''IRepositoryProvider'' allows components to enumerate version control repositories to be made available in Trac.

== Purpose ==
Trac can be connected to Version Control systems to e.g. [TracBrowser browse files], [TracChangeset visualize changesets] or [TracRevisionLog revision logs]. Plugins can hook into the version control system to extend the set of repositories that are available in Trac.

The main purpose for this interface is to allow plugins to implement new mechanisms to register, configure or auto-discover repositories.

(For implementing the actual mechanism that connects to a new ''type'' of repository use [../trac.versioncontrol.api.IRepositoryConnector IRepositoryConnector] instead.)

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

Trac automatically calls the `get_repositories` method to retrieve a list of dictionaries. Each dictionary represents a repository to connect to. The dictionaries dictionary which must contain at the very least either of the following entries:

- `'dir'`: the repository directory which can be used by the connector to create a `Repository` instance. This defines a "real" repository.
- `'alias'`: the name of another repository. This defines an alias to another (real) repository.

Optional entries:

- `'type'`: the type of the repository (if not given, the default repository type will be used).

- `'description'`: a description of the repository (can contain WikiFormatting).

- `'hidden'`: if set to `'true'`, the repository is hidden from the repository index.

- `'url'`: the base URL for checking out the repository.

Trac caches the list of repositories. You can call `RepositoryManager(self.env).reload_repositories()` to invalidate the cache and load the new list of repositories, e.g. if your plugin deletes or creates a new repository.

== Examples ==

[source:trunk/tracopt/versioncontrol/git/git_fs.py#/GitwebProjectsRepositoryProvider GitwebProjectsRepositoryProvider] provides all Git repositories listed in your Gitweb-formatted `projects.list` file.

Alternatively, you might simply want all the subdirectories of one parent directory to get auto-discovered as Git repositories:
{{{#!python
import os
from trac.config import PathOption
from trac.core import Component, implements
from trac.versioncontrol.api import IRepositoryProvider

class DirGitRepositoryProvider(Component):
    implements(IRepositoryProvider)

    projects_base = PathOption('git', 'projects_base', doc=
        """Path to the base of your git projects""")

    def get_repositories(self):
        for name in os.listdir(self.projects_base):
            repo = {
                'dir': os.path.join(self.projects_base, name),
                'type': 'git',
            }
            yield name, repo
}}}

== Available Implementations ==

* `trac.versioncontrol.api.DbRepositoryProvider`: Provides repositories registered in [TracRepositoryAdmin#ReposDatabase Trac DB].
* `trac.versioncontrol.api.RepositoryManager`: Provides repositories registered in `[repositories]` section of [TracRepositoryAdmin#ReposTracIni trac.ini].
* `tracopt.versioncontrol.git.git_fs.GitwebProjectsRepositoryProvider`: Provides repositories registered in a Gitweb-formatted `projects.list` file.
    
* th:TracSvnAdminPlugin: Provides all valid SVN repositories in a directory.
* th:HgDirManagerPlugin: Provides all HG repositories in a directory.

== Additional Information and References ==

 * [apiref:trac.versioncontrol.api.IRepositoryProvider-class epydoc]
 * [apidoc:api/trac_versioncontrol_api#trac.versioncontrol.api.IRepositoryProvider API Reference]
 * See [../trac.versioncontrol.api.IRepositoryConnector trac.versioncontrol.api.IRepositoryConnector], [../trac.versioncontrol.api.IRepositoryChangeListener trac.versioncontrol.api.IRepositoryChangeListener]
 * [TracDev/DatabaseSchema/VersionControl Version control cache database schema]

=== API History
 * [wiki:TracDev/ApiChanges/0.12#IRepositoryProvider 0.12] introduced the interface