VCI - A generic interface for interacting with various version-control systems.
my $repository = VCI->connect(type => $type, repo => $repo);
This is VCI, the generic Version Control Interface. The goal of VCI is to create a common API that can interface with all version control systems.
VCI uses Moose, so all constructors for all objects are called new (although for VCI itself you'll want to use "connect"), and they all take named parameters as a hash (not a hashref).
new
The VCI home page is at http://vci.everythingsolved.com/.
Note: The interface of all VCI modules should currently be considered UNSTABLE. I may make breaking changes in order to fix any design problems.
If you aren't sure where to start, you want to first look at "connect" and then at VCI::Abstract::Repository.
The general interface of VCI is described in the various VCI::Abstract modules, and those contain the documentation you should read in order to find out how VCI works.
"Drivers" for different VCSes are in modules whose names start with VCI::VCS. For example, VCI::VCS::Cvs is the "CVS support" for VCI. You only have to read VCI::VCS::Cvs or the manual of any other driver if you want to know:
VCI::VCS
The "connect" syntax for that driver.
The limitations of the driver. That is, any way that it differs from how VCI is supposed to work.
Explanations of things that might be surprising or unexpected when dealing with that particular version-control system.
Any extensions that that driver has implemented.
A server that contains your version-controlled files is considered a "repository", and is represented by VCI::Abstract::Repository.
An actual set of code that you could check out of the repository is considered a "project", and is represented by VCI::Abstract::Project.
Almost all information that VCI gives is in relation to the project. For example, file paths are relative to the base directory of the project, not the base directory of the entire repository.
For information on how to get a Project object from a Repository, see VCI::Abstract::Repository.
The general interface of VCI classes is described in the VCI::Abstract modules, but the specific implementations for particular VCSes are in the VCI::VCS namespace.
For example, the methods that you use on a File in your version-control system are described in VCI::Abstract::File, but the actual specific implementation for CVS is in VCI::Cvs::File. VCI::Cvs::File must implement all of the methods described in VCI::Abstract::File, but it also may implement extension methods whose names start with x_.
VCI::Cvs::File
x_
If you are going to use isa on objects to check their type, you should check that they are the abstract type, not the specific type. For example, to find out if an object is a File, you would do:
isa
$obj->isa('VCI::Abstract::File')
VCI has three-number version numbers, like this:
MAJOR.API.MINOR_DEVEL
MAJOR.API.MINOR
DEVEL
Here's what each number means:
As long as this number is 0, major breaking changes may occur to the API all the time. When this becomes 1, the API is stable. For numbers greater than 1, it means we made a major breaking change to the API.
0
1
For example, VCI 2.0.1 would have breaking changes for the user or for the drivers, compared to VCI 1.0.1. But VCI 0.1.1 and 0.2.1 could contain breaking changes between them, also, because the first number is still 0.
VCI has various features, but the drivers may not implement all of these features. So, when we add new features that drivers must implement, the API number gets incremented.
API
For example, VCI 0.0.1 doesn't have support for authenticating to repositories, but VCI 0.2.1 might support it.
Drivers will say which VCI API they support. Using a driver that doesn't support the current VCI API will throw a warning if "debug" mode is on. Using a driver that supports an API later than the current VCI will throw an error.
This indicates a bug-fix release, with the API staying the same.
This will always be 1 or higher unless this is a development release, in which case it will be 0.
If this is an unstable development release, this number will be included. In this case, the MINOR number should almost always be 0.
MINOR
connect
Returns a VCI::Abstract::Repository object based on your parameters. This is how you "start" using VCI.
Note that you cannot currently connect to repositories that require authentication, as VCI has no way of dealing with usernames or passwords. So you must connect to repositories that don't require authentication, or to which you have already authenticated. Future versions of VCI will support authentication.
repo
This is a string representing the repository you want to connect to, in the exact same format that you'd pass to the command-line interface to your VCS. For example, for CVS this would be the contents of CVSROOT.
CVSROOT
The documentation of individual drivers will explain what the format required for this field is.
Taint Mode: VCI will throw an error if this is tainted, because drivers use this string to do various operations (such as filesystem operations) that could be unsafe with untrusted data. If VCI didn't throw the error, you'd instead get some weird error from some internal part of VCI or one of the modules it uses, so it's better to just throw it right here.
type
What VCI driver you want to use. For example, to use CVS (VCI::VCS::Cvs) you'd say Cvs for this parameter. It is case-sensitive, and must be the name of an installed module in the VCI::VCS namespace.
Cvs
debug
If you'd like VCI to print out a lot of information about what it's doing to STDERR, set this to 1. Different drivers will print out different information.
STDERR
Some drivers will print out more information if you set debug to higher values than 1.
(Note: This is an IntBool.)
This has the same parameters as "connect", but actually returns a VCI object, not a VCI::Abstract::Repository.
VCI
You'll generally want use "connect" instead of this.
api_version
This is for drivers, to indicate what API version they implement.
Returns a hashref with two items:
major - The major version number of the VCI API that this driver implements.
major
api - The api version number of the VCI API that this driver implements.
api
For more information about what these numbers mean, see "VERSION NUMBERING SCHEME".
All of the fields that "connect" takes can also be accessed with methods named after them. In addition to the fields that you pass in to new, there are other accessors:
repository
Returns the VCI::Abstract::Repository that this VCI is connected to. Generally you don't want to use this, and you just want to use "connect".
VCI is available on CPAN, which is the recommended way to get it: http://search.cpan.org/dist/VCI/
VCI is also available from my source repository. You can get the latest development version by doing:
bzr co http://bzr.everythingsolved.com/vci/trunk
Note that if you check out code from my trunk repository, it may be unstable or completely broken.
You can get the latest stable version by doing:
bzr co http://bzr.everythingsolved.com/vci/stable
You have to do perl Build.PL and ./Build manifest on any checked- out code before you can install it.
perl Build.PL
./Build manifest
VCI strives to perform well. It will never perform faster than the VCS being used, however. Also, on very large projects (tens of thousands of files or tens of thousands of commits) some operations may be slow (such as asking for the History of an entire Project). However, for most uses and for the majority of projects, VCI should be fast enough.
Using local repositories is always faster than using remote repositories, usually by orders of magnitude.
VCI uses Moose extensively, so installing the latest version of Moose often helps improve the performance of VCI.
If the performance of VCI is too slow for your project, please let the author know using one of the mechanisms described in "SUPPORT". Without knowing exactly what sort of things are slow in real-world use, it's impossible to know what to optimize.
VCI has an IRC channel on irc.perl.org called #vci. If the author of VCI is awake and on the computer, he's usually there.
Otherwise, the best way to get support for VCI is just to email the author at mkanat@cpan.org.
mkanat@cpan.org
VCI also has a (currently minimal) home page at:
http://vci.everythingsolved.com/
VCI strives to work properly and safely under taint mode. Unless specified otherwise in their POD, all VCS drivers work correctly under taint mode.
Various methods check their arguments for being tainted and throw an error if they are. Methods that do this have a note about Taint Mode in their documentation.
This is information for people who want to hack on the internals of VCI or implement a driver for their VCS.
If the POD of the VCI::Abstract modules says something, that is an API for VCI. Unless the POD specifically says you can change the behavior of a method, you must not deviate from how the POD says the methods and accessors work.
VCI::Abstract
You may add new required attributes to the constructors of various modules, but you must not add required attributes to methods other than what is already specified in the POD for that method.
required
VCI provides a base set of functions that are common to all Version-Control Systems, but if your VCS can do special things, feel free to add extension methods.
So that your methods don't conflict with VCI methods, their names should start with x_ (or _x_ for private methods). VCI won't enforce that, but if you don't do it, your module could seriously break in the future if VCI implements a method with the same name as yours.
_x_
VCI promises not to have any standard methods or accesors that start with x_ or _x_.
In order of priority, the goals of VCI are:
Correctness
Ease of Driver Implementation
To implement as many VCS features as possible, not to only implement the common denominator of all VCSes.
Speed Efficiency
Memory Efficiency is a fourth consideration to be taken into account when writing drivers, but isn't considered as important as the above items.
This means that drivers (and VCI) should do exactly what the user asks, without any surprises or side-effects, and should conform fully to all required elements of the API.
If you have doubts about what is "correct", ask yourself the question, "What would be most logical for a web application that views and interacts with a repository?" That is the function that VCI was originally designed for.
VCI is designed to make life easy for implementors. The only things that you must implement are:
_build_projects
_build_history
_build_contents
_build_revision
_build_time
_build_as_diff
_build_content
That's basically the minimum you have to implement. The more you implement, the faster your VCI driver will be. But it will still be fully correct (if sometimes slow) with only the above implemented.
Many abstractions limit you to the common denominator of all the things they abstract. That is, we could say, "You can only do X with VCI if all VCSes can do X." But that's not the goal of VCI.
Instead, we say, "VCI allows you to do X. If the VCS can't do X, VCI will provide some reasonable default instead."
For example, not all VCSes track if a file is executable. But we provide "is_executable" in VCI::VCS::File, and it behaves sensibly when the VCS doesn't track that information.
In general, VCI strives to be efficient in terms of speed. Working with a version-control system can often be a slow experience, and we don't want to make that any worse than it already is.
This means that individual methods should do the least work possible to return the information that the user needs, and store it internally for later use.
For example, a file in a version control system has a first revision . If there's a fast way to just get the first revision, you should do that.
But if we've already read the whole history of a file, that has information about the first revision in it, so we should just be able to reference the history we already retrieved, instead of asking the version-control system for the first revision all over again.
This is just some tips to make your life easier if you're going to implement a driver for your version-control system.
First, you want to implement a method of connecting to your VCS, which means implementing VCI. Then VCI::Abstract::Repository, and then VCI::Abstract::Project.
After that you're probably going to want to implement VCI::Abstract::File and VCI::Abstract::Directory.
Then you can implement VCI::Abstract::History, and now that you have everything, you can implement VCI::Abstract::Commit.
In general, you shouldn't override "connect". Also, using before on "connect" probably also isn't a good idea. You could use after, but it mostly just makes sense to implement "build_repository" and leave it at that.
before
after
If you do override connect, you must call this connect at some point in your connect.
You must not add new required attributes to connect.
build_repository
Returns the VCI::Abstract::Repository object. (This is basically what "connect" returns, so this does the "heavy_lifting" for "connect".)
Drivers: VCI::VCS::Svn, VCI::VCS::Bzr, VCI::VCS::Hg, VCI::VCS::Git, and VCI::VCS::Cvs
Eventually the drivers will be split into their own packages.
Need user and pass support for "connect".
user
pass
Come up with a meaningful "branch" abstraction.
Commits need to understand parent and children, for VCSes like Hg and Git that don't necessarily have a linear series of commits.
parent
children
Commits need to have a subcommits accessor that gives minor commits that are part of this larger commit. (For example, "merge commits" in bzr or git.)
subcommits
"moved" in VCI::Abstract::Commit should be a hashref that points to objects, not to strings.
VCI is very new, and probably has many significant bugs. The code is no better than alpha-quality at this point. However, VCI's test suite has nearly 100% code coverage, and VCI currently passes all tests.
Max Kanat-Alexander <mkanat@cpan.org>
Copyright 2007-2008 by Everything Solved, Inc.
http://www.everythingsolved.com
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install VCI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm VCI
CPAN shell
perl -MCPAN -e shell install VCI
For more information on module installation, please visit the detailed CPAN module installation guide.