Introduction to using VersionControl_SVN Using VersionControl_SVN to manage a Subversion repository Clay Loveless {@link mailto:clay@killersoft.com clay@killersoft.com} Copyright 2004, Clay Loveless {@toc} Introduction VersionControl_SVN is a simple Object-Oriented interface for the svn command-line application that makes up the core of {@link http://subversion.tigris.org/ Subversion}, a free/open-source version control system. Subversion can be used to manage trees of source code, text files, image files -- just about any collection of files. VersionControl_SVN's features include: Full support of svn subcommands. Flexible error reporting provided by {@link http://pear.php.net/manual/en/core.pear.pear-errorstack.php PEAR_ErrorStack} Multi-object factory design. Fully documented source code The power of a version control system like Subversion, when accessed through VersionControl_SVN, can be extended far beyond typical "source code" repositories. For example, what content management system (CMS) couldn't benefit from version control functionality? For many non-programmers, version control is a confusing subject to get a firm grasp on. With VersionControl_SVN, developers are now able to customize the interface to Subversion with the ease-of-use goals of their particular audience in mind. VersionControl_SVN lets you leverage the strengths of version control without burdening end-users with the learning curve of change control fundamentals. A Simple Example So you've got Subversion repository set up somewhere, and you want to take a look at what's inside with a PHP script. With the {@link VersionControl_SVN::VersionControl_SVN_List()} command, you're just a few steps away. VERSIONCONTROL_SVN_FETCHMODE_ARRAY); // Request list class from factory $svn = VersionControl_SVN::factory('list', $options); // Define any switches and aguments we may need $switches = array('username' => 'user', 'password' => 'pass'); $args = array('svn://svn.example.com/repos/TestProject'); // Run command if ($output = $svn->run($args, $switches)) { print_r($output); } else { if (count($errs = $svnstack->getErrors())) { foreach ($errs as $err) { echo '
'.$err['message']."
\n"; echo "Command used: " . $err['params']['cmd']; } } } ?> ]]> If your example repository above happened to have the VersionControl_SVN source in it, your output would be something like this: Array ( [name] => docs [type] => D ) [1] => Array ( [name] => package.xml [type] => F ) [2] => Array ( [name] => SVN.php [type] => F ) [3] => Array ( [name] => SVN [type] => D ) [4] => Array ( [name] => tests [type] => D ) ) ?> ]]> Note that in the above output, directories are flagged as type D, and files are flagged as type F. Note: For additional information in the output, try setting verbose to true in your $options array. One Factory To Rule Them All Have a script that needs to utilize several VersionControl_SVN subclasses? At the expense of a little overhead, you can be sure your $svn objects are fully-loaded by using the {@link VersionControl_SVN::factory()} command keyword __ALL__. For example, in a basic script to get the list of current files in a repository, you just need the {@link VersionControl_SVN::VersionControl_SVN_List()} subclass. VERSIONCONTROL_SVN_FETCHMODE_ARRAY); // Request list class from factory $svn = VersionControl_SVN::factory('list', $options); // Define any switches and aguments we may need $switches = array('username' => 'user', 'password' => 'pass'); $args = array('svn://svn.example.com/repos/TestProject'); // Run command if ($output = $svn->run($args, $switches)) { print_r($output); } else { if (count($errs = $svnstack->getErrors())) { foreach ($errs as $err) { echo '
'.$err['message']."
\n"; echo "Command used: " . $err['params']['cmd']; } } } ?> ]]> However, if you need to get a recursive list of files in a repository, look up the recent log activity for those files, and view the annotated source for those files, you've got two options. VERSIONCONTROL_SVN_FETCHMODE_RAW); // METHOD ONE: Lowest Overhead // Create svn object with subcommands we need listed out individually $svn = VersionControl_SVN::factory(array('list', 'log', 'blame'), $options); // Define any switches and aguments we may need $switches = array('username' => 'user', 'password' => 'pass'); $args = array('svn://svn.example.com/repos/TestProject'); print_r($svn->list->run($args, $switches)); // Pick files out of the above output, and see who did what $args = array('svn://svn.example.com/repos/TestProject/trunk/index.php'); echo "
" . $svn->blame->run($args) . "
"; // METHOD TWO: Put all available commands at your disposal // Load up all subcommands - higher overhead, but convenient for certain occasions $svn = VersionControl_SVN::factory('__ALL__', $options); // Now you may run whatever you need to ... $svn->cat->run($args, $switches); $svn->info->run($args, $switches); // ... and so on. ?> ]]> Further Reading If you are interested in learning more about Subversion, see the following: {@link http://svnbook.red-bean.com/ Version Control with Subversion} - The primary reference manual for all things related to Subversion, from general use to repository administration. {@link http://subversion.tigris.org/ Subversion Website} - The official Subversion website offers a FAQ, mailing list, and of course, the Subversion source code. Also included are links to GUI Subversion applications.