This module implements an abstraction layer over different kind of version control systems and the mechanism to access several heterogeneous repositories under a single “virtual” hierarchy.
This abstraction was derived from the original model built around the Subversion system (versioned tree, changesets). It gradually became more general, now aiming at supporting distributed version control systems (DVCS).
Provide support for a specific version control system.
See also trac.versioncontrol.api.IRepositoryConnector extension point
Return a Repository instance for the given repository type and dir.
Return the types of version control systems that are supported.
Yields (repotype, priority) pairs, where repotype is used to match against the configured [trac] repository_type value in TracIni.
If multiple provider match a given type, the priority is used to choose between them (highest number is highest priority).
If the priority returned is negative, this indicates that the connector for the given repotype indeed exists but can’t be used for some reason. The error property can then be used to store an error message or exception relevant to the problem detected.
Provide known named instances of Repository.
See also trac.versioncontrol.api.IRepositoryProvider extension point
Generate repository information for known repositories.
Repository information is a key,value pair, where the value is a 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.
Listen for changes in repositories.
See also trac.versioncontrol.api.IRepositoryChangeListener extension point
Called after a changeset has been added to a repository.
Version control system manager.
List of components that implement IRepositoryChangeListener
List of components that implement IRepositoryConnector
Return a dictionary of repository information, indexed by name.
Recover the appropriate repository from the current context.
Lookup the closest source or changeset resource in the context hierarchy and return the name of its associated repository.
Return a set of all real repositories (i.e. excluding aliases).
Retrieve repositories specified in TracIni.
The [repositories] section can be used to specify a list of repositories.
Retrieve the repositories based on the given directory.
| Parameters: | directory – the key for identifying the repositories. |
|---|---|
| Returns: | list of Repository instances. |
Retrieve the appropriate Repository for the given repository name.
| Parameters: | reponame – the key for specifying the repository. If no name is given, take the default repository. |
|---|---|
| Returns: | if no corresponding repository was defined, simply return None. |
| Raises InvalidRepository: | |
| if the repository cannot be opened. | |
Retrieve a matching Repository for the given path.
| Parameters: | path – the eventually scoped repository-scoped path |
|---|---|
| Returns: | a (reponame, repos, path) triple, where path is the remaining part of path once the reponame has been truncated, if needed. |
Return a unique id for the given repository name.
This will create and save a new id if none is found.
Return the list of supported repository types.
Notify repositories and change listeners about repository events.
The supported events are the names of the methods defined in the IRepositoryChangeListener interface.
List of components that implement IRepositoryProvider
Reload the repositories from the providers.
One of the alternatives for registering new repositories is to populate the [repositories] section of the trac.ini.
This is especially suited for setting up convenience aliases, short-lived repositories, or during the initial phases of an installation.
See [TracRepositoryAdmin#Intrac.ini TracRepositoryAdmin] for details about the format adopted for this section and the rest of that page for the other alternatives.
(‘’since 0.12’‘)
Path to the default repository. This can also be a relative path (‘’since 0.11’‘).
This option is deprecated, and repositories should be defined in the [TracIni#repositories-section repositories] section, or using the “Repositories” admin panel. (‘’since 0.12’‘)
List of repositories that should be synchronized on every page request.
Leave this option empty if you have set up post-commit hooks calling trac-admin $ENV changeset added on all your repositories (recommended). Otherwise, set it to a comma-separated list of repository names. Note that this will negatively affect performance, and will prevent changeset listeners from receiving events from the repositories specified here. The default is to synchronize the default repository, for backward compatibility. (‘’since 0.12’‘)
Default repository connector type. (‘’since 0.10’‘)
This is also used as the default repository type for repositories defined in [[TracIni#repositories-section repositories]] or using the “Repositories” admin panel. (‘’since 0.12’‘)
Free Repository instances bound to a given thread identifier
Component providing repositories registered in the DB.
Create an alias repository.
Add a repository.
Retrieve repositories specified in the repository DB table.
Modify attributes of a repository.
Remove a repository.
Subclasses of ResourceNotFound.
Base class for a repository provided by a version control system.
Initialize a repository.
| Parameters: |
|
|---|---|
| Raises InvalidRepository: | |
if the repository cannot be opened. |
|
Return True if view permission is granted on the repository.
Clear any data that may have been cached in instance properties.
youngest_rev can be specified as a way to force the value of the youngest_rev property (‘’will change in 0.12’‘).
Close the connection to the repository.
Return a representation of a revision in the repos for displaying to the user.
This can be a shortened revision string, e.g. for repositories using long hashes.
| Raises NoSuchChangeset: | |
|---|---|
| If the given rev isn’t found. | |
Return the name of the base repository for this repository.
This function returns the name of the base repository to which scoped repositories belong. For non-scoped repositories, it returns the repository name.
Generates changes corresponding to generalized diffs.
Generator that yields change tuples (old_node, new_node, kind, change) for each node change between the two arbitrary (path,rev) pairs.
The old_node is assumed to be None when the change is an ADD, the new_node is assumed to be None when the change is a DELETE.
Retrieve a Changeset corresponding to the given revision rev.
Return a globally unique identifier for the ‘’rev’’ changeset.
Two changesets from different repositories can sometimes refer to the ‘’very same’’ changeset (e.g. the repositories are clones).
Generate Changeset belonging to the given time period (start, stop).
Retrieve a Node from the repository at the given path.
A Node represents a directory or a file at a given revision in the repository. If the rev parameter is specified, the Node corresponding to that revision is returned, otherwise the Node corresponding to the youngest revision is returned.
Return the oldest revision stored in the repository.
Retrieve all the revisions containing this path.
If given, rev is used as a starting point (i.e. no revision ‘’newer’’ than rev should be returned). The result format should be the same as the one of Node.get_history()
Return the repository URL for the given path and revision.
The returned URL can be None, meaning that no URL has been specified for the repository, an absolute URL, or a scheme-relative URL starting with //, in which case the scheme of the request should be prepended.
Generate a list of interesting places in the repository.
rev might be used to restrict the list of available locations, but in general it’s best to produce all known locations.
The generated results must be of the form (category, name, path, rev).
Return the youngest revision in the repository.
Tell if there’s a node at the specified (path,rev) combination.
When rev is None, the latest revision is implied.
Return True if view permission is granted on the repository.
Return the revision immediately following the specified revision.
If path is given, filter out descendant revisions having no changes below path.
In presence of multiple children, this follows the first child.
Return a canonical representation of path in the repos.
Return a (unique) canonical representation of a revision.
It’s up to the backend to decide which string values of rev (usually provided by the user) should be accepted, and how they should be normalized. Some backends may for instance want to match against known tags or branch names.
In addition, if rev is None or ‘’, the youngest revision should be returned.
| Raises NoSuchChangeset: | |
|---|---|
| If the given rev isn’t found. | |
Return a list of parents of the specified revision.
Return the revision immediately preceding the specified revision.
If path is given, filter out ancestor revisions having no changes below path.
In presence of multiple parents, this follows the first parent.
Provides a total order over revisions.
Return True if rev1 is an ancestor of rev2.
Return a compact representation of a revision in the repos.
| Raises NoSuchChangeset: | |
|---|---|
| If the given rev isn’t found. | |
Perform a sync of the repository cache, if relevant.
If given, rev_callback must be a callable taking a rev parameter. The backend will call this function for each rev it decided to synchronize, once the synchronization changes are committed to the cache. When clean is True, the cache is cleaned first.
Represents a directory or file in the repository at a given revision.
Return True if view permission is granted on the node.
Provide detailed backward history for the content of this Node.
Retrieve an array of revisions, one rev for each line of content for that node. Only expected to work on (text) FILE nodes, of course.
Return a stream for reading the content of the node.
This method will return None for directories. The returned object must support a read([len]) method.
The MIME type corresponding to the content, if known.
Will be None for a directory.
Generator that yields the immediate child entries of a directory.
The entries are returned in no particular order. If the node is a file, this method returns None.
Provide backward history for this Node.
Generator that yields (path, rev, chg) tuples, one for each revision in which the node was changed. This generator will follow copies and moves of a node (if the underlying version control system supports that), which will be indicated by the first element of the tuple (i.e. the path) changing. Starts with an entry for the current revision.
| Parameters: | limit – if given, yield at most limit results. |
|---|
Return the change event corresponding to the previous revision.
This returns a (path, rev, chg) tuple.
Return a stream for reading the content of the node, with some standard processing applied.
| Parameters: |
|
|---|
Returns the properties (meta-data) of the node, as a dictionary.
The set of properties depends on the version control system.
Return True if view permission is granted on the node.
Represents a set of changes committed at once in a repository.
Return True if view permission is granted on the changeset.
Yield branches to which this changeset belong. Each branch is given as a pair (name, head), where name is the branch name and head a flag set if the changeset is a head for this branch (i.e. if it has no children changeset).
Generator that produces a tuple for every change in the changeset.
The tuple will contain (path, kind, change, base_path, base_rev), where change can be one of Changeset.ADD, Changeset.COPY, Changeset.DELETE, Changeset.EDIT or Changeset.MOVE, and kind is one of Node.FILE or Node.DIRECTORY. The path is the targeted path for the change (which is the ‘’deleted’’ path for a DELETE change). The base_path and base_rev are the source path and rev for the action (None and -1 in the case of an ADD change).
Returns the properties (meta-data) of the node, as a dictionary.
The set of properties depends on the version control system.
Warning: this used to yield 4-elements tuple (besides name and text, there were wikiflag and htmlclass values). This is now replaced by the usage of IPropertyRenderer (see #1601).
Yield tags associated with this changeset.
New in version 1.0.
Return True if view permission is granted on the changeset.
