Arbit - project tracking

VCS wrapper documentation

The VCS (version control system) wrapper basically provides a RecursiveIterator for a repository to iterator over all its contents, similar to the RecursiveDirectoryIterator known from SPL. The returned objects from the iterator either implement vcsFile or vcsDirectory, which are the two types of handled resources.

Depending on the features of the respective VCS the vcsFile and vcsDirectory implementations for a VCS may implement additional interfaces. These interface provide access to additional features of the VCS. By default vcsFile offers access to the mime type and contents of a file, while vcsDirectoy offers an Interator for the directory contents.

Interfaces

Additional interfaces, which may be implemented for a VCS, are:

• vcsVersioned

  The basic interface for all VCS, which support versioning of contents, which should be common. This is not implemented by the Archive wrapper. It offers methods to access the current version of a resource or questioning all existing versions.

  All the following interfaces extend from this basic interface.

• vcsAuthored

  Implements getAuthor() for VCS which support author information

• vcsBlameable

  Extends from vcsAuthored and vcsVersioned, and is implemented, if the VCS allows line wise blames of a resource in the directory, to check who when did the last change to a line in a file.

• vcsDiffable

  Implemented, if the VCS allows to display a diff between different versions of a resource.

• vcsFetchable

  Implemented, if the VCS allows to directly fetch older versions of a resource.

• vcsLogged

  Implemented, if the VCS maintainers a log with messages associated to revisions commited for each resource.

Additional interfaces may be implemented, if a VCS even includes more relevant information, then the listed. A class diagram, which shows the interfaces and the wrappers implementing those interfaces is attached.

Usage

The usage is shown as an example for the SVN Cli wrapper, but this would work the same for the other wrappers, when exchanging the relevant class names.

All repositories need to actually check out the contents of the repository to some path. This directory may or may not exist:

$checkout = new vcsSvnCliCheckout( '/tmp/checkout' );

Since meta data, like revision logs, may take a long time to fetch, all such information is cached. In big repositories with lots of revisions the cache data could exceed commonly available space, so that the cache also implements a cache size limitation, using LRU. The cache has to be initialized before any operation on the repository:

vcsCache::initialize( '/tmp/cache' );

After that you may initialize the repository using the URL of the repository, of a path to the archive for the archive wrapper:

$checkout->initialize( 'svn://arbitracker.org/vcs_wrapper/trunk' );

You may optionally pass a user and password as the second and third argument, which is not necessary for repositories allowing anonymous access.

The checkout also implements the vcsDirectoy interface, so that you can directly start iterating over the repository contents, like:

$iterator = new RecursiveIteratorIterator( $checkout, RecursiveIteratorIterator::SELF_FIRST );

$files = array();
foreach ( $iterator as $resource )
{
    echo (string) $resource, "\n";
}

If you want to directly access a file or directory to operate on, you may also directly access that resource, for example like:

$dir = new vcsSvnCliDirectory( '/tmp/checkout', '/src' );

The first argument is the location of the checkout, and the second the absolute path inside the checkout. These resources may implement, depending on the used VCS, the additional methods offered by the above mentioned interfaces, so you then could dump the log of the source directory using:

$log = $dir->getLog();
foreach ( $log as $logEntry )
{
    printf( "%s in %s: %s\n",
        $logEntry->author,
        $logEntry->version,
        $logEntry->message
    );
}

Initialize vcsWrapper

To load all classes used by the vcsWrapper you may either integrate it in your autoload mechanism, or load all classes directly. To integrate vcsWrapper in you autoload mechanism, the file classes/autoload.php returns an array with all classes and their location in the files system.

This array may also be used to directly include all files, because the array is already topologically sorted depending on the class hierarchy, like:

$files = include ( $base = '/path/to/vcs_wrapper/' ) . 'classes/autoload.php';
foreach ( $files as $class => $file )
{
        require_once $base . $file;
}

We hope you enjoy using the VCS wrapper.