VCS wrapper, tracked with Arbit

Edit wiki page

You do not have sufficant permissions to edit or create the wiki page.
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.

__ http://www.php.net/~helly/php/ext/spl/interfaceRecursiveIterator.html
__ http://www.php.net/~helly/php/ext/spl/classRecursiveDirectoryIterator.html

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.

__ Start/class_diagram.png

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
        );
    }

__ http://en.wikipedia.org/wiki/Cache_algorithms

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.
Arbit - project tracking

VCS wrapper

Edit wiki page
