/ 
VcsTools-History-1.002
/ VcsTools::History

NAME

VcsTools::History - Perl class to manage a VCS history.

SYNOPSIS

require VcsTools::DataSpec::HpTnd ; # for instance
my $ds = new VcsTools::DataSpec::HpTnd ;
my $hist = new VcsTools::History 
 (
  keyRoot => 'history root',
  name => 'History test',
  dataScanner => $ds
 );

DESCRIPTION

This class represents a whole history of a VCS file. It holds all the necessary VcsTools::Version objects that makes the complete history of the file.

Generally, RCS based systems such as VCS or HMS store a few information with each revision. These information are generally 'Author', 'date', 'branches', 'log'. On top of the common informations, you can specify your own set of information (for instance, 'merged from', 'bug fixed') according to the policies defined on your work place.

On top of the functionnality of the Version object (See "DESCRIPTION" in VcsTools::Version), you can perform various queries related to the history such as :

  • Sort revisions: it will return a pair of revisions sorted by age. Oldest and child. But it will return an error if these two versions are not parents of each others.

  • List a genealogy of versions between 2 revisions of a file. This will take into account the branches. For instance between 1.1 and 1.2.1.2, it will return 1.1 1.2 1.2.1.1 1.2.1.2), but between 1.3 and 1.2.1.2 it will return an error, since these two versions are not parents of each others.

  • Build a cumulated log of several revisions. I.e a log description of all changes made to several consecutive versions (which is handy to build a log of a merge). This function will return an if these two versions are not parents of each others.

Furthermore, this class can be used with a GUI by using Puppet::VcsTools::History instead.

CONVENTION

The following words may be non ambiguous for native english speakers, but it is not so with us french people. So I prefer clarify these words:

  • Log: Refers to the information stored with one version.

  • History: Refers to a collection of all logs of all versions stored in the VCS base.

Constructor

new(...)

Will create a new history object.

Parameters are those of Puppet::Body plus :

Methods

update(...)

Parameters are:

  • history: huge string or array ref of all VCS logs, or history hash ref using the format described in data scanner

This method will:

  • Parse the content of the history.

  • Create all Version objects found in the history

  • Update all Version objects with the informations found in each log.

Note that calling this method will clobber all informations previously stored in the Version objects.

hasVersion(revision)

Returns 1 if the VCS file contains this revision of the file.

guessNewRev(revision)

Returns a fitting revision number to follow the passed revision.

For instance :

  • guessNewRev(1.2) returns 1.3 if 1.3 does not exist

  • guessNewRev(1.2) returns 1.2.1.1 if 1.3 already exists

  • guessNewRev(1.2) returns 1.2.2.1 if 1.3 and branch 1.2.1 already exist

sortRevisions($rev1, $rev2)

Returns ($rev1, $rev2) if $rev1 is the ancestor of $rev2, ($rev2, $rev1) in the other case.

Returns undef if the revisions are not parents.

listGenealogy($rev1, $rev2)

Returns a list of all revision between $rev1 and $rev2. Include the youngest revision in the list, but not the older.

Croaks if the revision are not parents.

getInfo($rev)

Returns an info array containing all informations relevant to $rev.

buildCumulatedInfo($rev1, $rev2)

Returns an info array made of a concatenation of all revision between $rev1 and $rev2.

Croaks if the revisions are not parents.

addNewVersion(...)

Parameters are:

  • revision: revision to add (e.g. '1.2.1.1')

  • info: hash ref containing the informations related to this revision.

This method will add a new version in this history. Do not call this method unless the VCS system actually has a new version, i.e. the user just performed an archive.

getVersionObj(revision)

Returns the object ref of the Version object representing the passed revision. Will create the objects as necessary.

Returns undef if the asked revision does not exist.

AUTHOR

Dominique Dumont, Dominique_Dumont@grenoble.hp.com

Copyright (c) 1998-1999 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), VcsTools::DataSpec::HpTnd(3), VcsTools::DataSpec::Rcs(3) VcsTools::Version(3), Puppet::VcsTools::History(3)