Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.api.IRepositoryProvider


Ignore:
Timestamp:
Jul 21, 2014, 10:45:52 PM (6 years ago)
Author:
Peter Suter
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.api.IRepositoryProvider

    v1 v1  
     1== Extension Point : ''IRepositoryProvider'' ==
     2
     3||'''Interface'''||''IRepositoryProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IRepositoryProvider 0.12]||
     4||'''Module'''||''trac.versioncontrol.api''||'''Source'''||[source:trunk/trac/versioncontrol/api.py#/IRepositoryProvider api.py]||
     5
     6The ''IRepositoryProvider'' allows components to enumerate version control repositories to be made available in Trac.
     7
     8== Purpose ==
     9Trac 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.
     10
     11The main purpose for this interface is to allow plugins to implement new mechanisms to register, configure or auto-discover repositories.
     12
     13(For implementing the actual mechanism that connects to a new ''type'' of repository use [../trac.versioncontrol.api.IRepositoryConnector IRepositoryConnector] instead.)
     14
     15== Usage ==
     16
     17Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     18
     19Trac 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:
     20
     21- `'dir'`: the repository directory which can be used by the connector to create a `Repository` instance. This defines a "real" repository.
     22- `'alias'`: the name of another repository. This defines an alias to another (real) repository.
     23
     24Optional entries:
     25
     26- `'type'`: the type of the repository (if not given, the default repository type will be used).
     27
     28- `'description'`: a description of the repository (can contain WikiFormatting).
     29
     30- `'hidden'`: if set to `'true'`, the repository is hidden from the repository index.
     31
     32- `'url'`: the base URL for checking out the repository.
     33
     34Trac 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.
     35
     36== Examples ==
     37
     38[source:trunk/tracopt/versioncontrol/git/git_fs.py#/GitwebProjectsRepositoryProvider GitwebProjectsRepositoryProvider] provides all Git repositories listed in your Gitweb-formatted `projects.list` file.
     39
     40Alternatively, you might simply want all the subdirectories of one parent directory to get auto-discovered as Git repositories:
     41{{{#!python
     42import os
     43from trac.config import PathOption
     44from trac.core import Component, implements
     45from trac.versioncontrol.api import IRepositoryProvider
     46
     47class DirGitRepositoryProvider(Component):
     48    implements(IRepositoryProvider)
     49
     50    projects_base = PathOption('git', 'projects_base', doc=
     51        """Path to the base of your git projects""")
     52
     53    def get_repositories(self):
     54        for name in os.listdir(self.projects_base):
     55            repo = {
     56                'dir': os.path.join(self.projects_base, name),
     57                'type': 'git',
     58            }
     59            yield name, repo
     60}}}
     61
     62== Available Implementations ==
     63
     64* `trac.versioncontrol.api.DbRepositoryProvider`: Provides repositories registered in [TracRepositoryAdmin#ReposDatabase Trac DB].
     65* `trac.versioncontrol.api.RepositoryManager`: Provides repositories registered in `[repositories]` section of [TracRepositoryAdmin#ReposTracIni trac.ini].
     66* `tracopt.versioncontrol.git.git_fs.GitwebProjectsRepositoryProvider`: Provides repositories registered in a Gitweb-formatted `projects.list` file.
     67   
     68* th:TracSvnAdminPlugin: Provides all valid SVN repositories in a directory.
     69* th:HgDirManagerPlugin: Provides all HG repositories in a directory.
     70
     71== Additional Information and References ==
     72
     73 * [apiref:trac.versioncontrol.api.IRepositoryProvider-class epydoc]
     74 * [apidoc:api/trac_versioncontrol_api#trac.versioncontrol.api.IRepositoryProvider API Reference]
     75 * See [../trac.versioncontrol.api.IRepositoryConnector trac.versioncontrol.api.IRepositoryConnector], [../trac.versioncontrol.api.IRepositoryProvider trac.versioncontrol.api.IRepositoryProvider]
     76 * [TracDev/DatabaseSchema/VersionControl Version control cache database schema]
     77
     78=== API History
     79 * [wiki:TracDev/ApiChanges/0.12#IRepositoryProvider 0.12] introduced the interface