NAME
VCS::Lite::Repository - Minimal version Control system - Repository object
SYNOPSIS
use VCS::Lite::Repository;
my $rep = VCS::Lite::Repository->new($ENV{VCSROOT});
my $dev = $rep->check_out('/home/me/dev');
$dev->add_element('testfile.c');
$dev->add_repository('sub');
$dev->traverse(\&do_something);
$dev->check_in( description => 'Apply change');
$dev->update;
$dev->commit;DESCRIPTION
VCS::Lite::Repository is a freestanding version control system that is platform independent. The module is pure perl, and only makes use of other code that is available for all platforms.
new
my $rep = VCS::Lite::Repository->new('/local/fileSystem/path',
store => 'inSituYAML');A new repository object is created and associated with a directory on the local file system. If the directory does not exist, it is created. If the directory does not contain a repository, an empty repository is created.
The store parameter here is used to designate the store in which the repository is held. This parameter can be an object, a class or a string representing a package name inside VCS::Lite::Repository::Store. The default is inSituStorable; also available in the distribution is inSituYAML, which requires YAML to be installed, but makes repositories and elements that are human readable.
The control files associated with the repository live under a directory .VCSLite inside the associated directory (_VCSLITE on VMS as dots are not allowed in directory names on this platform), and these are in YAML format. The repository directory can contain VCS::Lite elements (which are version controlled), other repository diretories, and also files and directories which are not version controlled.
add
my $ele = $rep->add('foobar.pl');
my $ele = $rep->add('mydir');If given a directory, returns a VCS::Lite::Repository object for the subdirectory. If this does not already have a repository, one is created.
Otherwise it returns the VCS::Lite::Element object corresponding to a file of that name. The element is added to the list of elements inside the repository. If the file does not exist, it is created as zero length. If the file does exist, its contents become the generation 0 baseline for the element, otherwise generation 0 is the empty file.
The methods add_element and add_repository do the same thing, but check to make sure that the paremeter is a plain file (or a directory in the case of add_repository) and return if this is not the case. Add_repository will also create the directory if it does not exist.
remove
$rep->remove('foobar.pl');This is the opposite of add. It does not delete any files, merely removes the association between the repository and the element or subrepository.
traverse
$rep->traverse(\&mysub);
$rep->traverse('name', recurse => 1);
$rep->traverse('bar_method', params => ['bar', 1]);Apply a callback to each element and repository inside the repository. You can supply a method, such as 'name', which results in the method being called for all members of the repository rep, or you can supply your own code in a coderef (the first parameter passed will still be the object traversed. Return values are passed through traverse as a list.
If you specify a true value for the recurse option, traverse will also be called on each member of $rep. This has no effect on elements (VCS::Lite::Element->traverse returns undef). Return values from a recursion pass appear as an arrayref in the output. If you specify the parameter recurse as the value 'pre', traverse will be called on each member before the action being applied.
Of course, the action can do its own recursion, instead of traverse itself applying the recursion. traverse is used internally to implement check_out, check_in, commit and update methods.
check_out
my $newrep = $rep->check_out( store => 'YAML');Note: prior to version 0.08, this was known as clone, but the API has changed to use a more meanningful name.
Checking out generates a new tree of repositories and elements, putting in place a relationship between the repositories; the original is the parent repository.
The new repository does not have to use the same repository store as the parent.
check_in
Note: this is not the opposite operation to check_out. Use this method when you have changes that you want to go into a repository.
commit
This method is used to propagate a change from a repository to its parent.
update
This method applies changes that have happened to the parent, to the repository. This will merge with any changes in the current repository.
repositories
Return the currently available repositories.
add_repository
Add a repository to the current parent.
elements
Return the list of elements in the current repository.
add_element
Add an element to the current repository.
contents
Returns the full contents of the current repository, as objects.
fetch
Returns the VCS object for a given generation, or the latest generation.
ENVIRONMENT VARIABLES
USER
The environment variable USER is used to determine the author of changes. In a Unix environment, this should be adequate for out-of-the-box use. An additional environment variable, VCSLITE_USER is also checked, and this takes precedence.
Windows users will need to set one of these environment variables, or the application will croak with "Author not specified".
For more dynamic applications (such as CGI scripts that run as WWW, but receive the username from a cookie), you can set the package variable: $VCS::Lite::Repository::username. Note: there could be some problems with Modperl here - patches welcome.
TO DO
Integration with VCS suite.
SEE ALSO
VCS::Lite::Element, VCS::Lite, YAML.
BUGS, PATCHES & FIXES
There are no known bugs at the time of this release. However, if you spot a bug or are experiencing difficulties that are not explained within the POD documentation, please send an email to barbie@cpan.org or submit a bug to the RT system (see link below). However, it would help greatly if you are able to pinpoint problems or even supply a patch.
http://rt.cpan.org/Public/Dist/Display.html?Name=VCS-Lite-Repository
Fixes are dependent upon their severity and my availability. Should a fix not be forthcoming, please feel free to (politely) remind me.
AUTHOR
Original Author: Ivor Williams (RIP) 2002-2009
Current Maintainer: Barbie <barbie@cpan.org> 2014-2015COPYRIGHT
Copyright (c) Ivor Williams, 2002-2009
Copyright (c) Barbie, 2014-2015LICENCE
This distribution is free software; you can redistribute it and/or modify it under the Artistic Licence v2.