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

Timestamp:

Jul 21, 2014, 10:45:52 PM (10 years ago)

Author:

Peter Suter

Comment:

—

TracDev/PluginDevelopment/ExtensionPoints/trac.versioncontrol.api.IRepositoryProvider

@@ +1 @@
+== 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.IRepositoryProvider trac.versioncontrol.api.IRepositoryProvider]
+ * [TracDev/DatabaseSchema/VersionControl Version control cache database schema]
+
+=== API History
+ * [wiki:TracDev/ApiChanges/0.12#IRepositoryProvider 0.12] introduced the interface