Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VCS::CVS(3)	      User Contributed Perl Documentation	   VCS::CVS(3)

NAME
       "VCS::CVS" - Provide a simple interface to CVS (the Concurrent Versions
       System).

SYNOPSIS
	       #!/usr/gnu/bin/perl -w

	       use strict;

	       use VCS::CVS;

	       my($history)	   = 1;
	       my($initialMsg)	   = 'Initial version';
	       my($noChange)	   = 1;
	       my($nullTag)	   = '';
	       my($permissions)	   = 0775;     # But not '0775'!
	       my($project)	   = 'project';
	       my($projectSource)  = 'projectSource';
	       my($raw)		   = 0;
	       my($readOnly)	   = 0;
	       my($releaseTag)	   = 'release_0.00';
	       my($vendorTag)	   = 'vendorTag';
	       my($verbose)	   = 1;

	       # Note the anonymous hash in the	next line, new as of V 1.10.

	       my($cvs)		   = VCS::CVS -> new({
				       'project' => $project,
				       'raw' =>	$raw,
				       'verbose' => $verbose,
				       'permissions' =>	$permissions,
				       'history' => $history});

	       $cvs -> createRepository();
	       $cvs -> populate($projectSource,	$vendorTag, $releaseTag, $initialMsg);
	       $cvs -> checkOut($readOnly, $nullTag, $project);

	       print join("\n",	@{$cvs -> update($noChange)});
	       print "\n";
	       print join("\n",	@{$cvs -> history()});

	       exit(0);

DESCRIPTION
       The "VCS::CVS" module provides an OO interface to CVS.

       VCS - Version Control System - is the prefix given to each Perl module
       which deals with	some sort of source code control system.

       I have seen CVS corrupt binary files, even when run with	CVS's binary
       option -kb.  So,	since CVS doesn't support binary files,	neither	does
       VCS::CVS.

       Stop press: CVS V 1.10 (with RCS	5.7) supports binary files.

       Subroutines whose names start with a '_'	are not	normally called	by
       you.

       You need	to be clear in your mind about the 4 directories involved:

       o   The directory where your source code	resides	before you import it
	   into	CVS.  It is used only once - during the	import phase. Call
	   this	$projectSource.

       o   The directory into which you	check out a read-write copy of the
	   repository, in order	to edit	that copy. Call	this $project. You
	   will	spend up to 100% of your time working within this directory
	   structure.

       o   The directory in which the repository resides. This is $CVSROOT.
	   Thus	$projectSource will be imported	into $CVSROOT/$project.

       o   The directory into which you	get a read-only	copy of	the
	   repository, in order	to, say, make and ship that copy. Call this
	   $someDir. It	must not be $project.

       Note: You cannot	have a directory called	CVS in your home directory.
       That's just asking for trouble.

INSTALLATION
       You install "VCS::CVS", as you would install any	perl module library,
       by running these	commands:

	       perl Makefile.PL
	       make
	       make test
	       make install

       If you want to install a	private	copy of	"VCS::CVS" in your home
       directory, then you should try to produce the initial Makefile with
       something like this command:

	       perl Makefile.PL	LIB=~/perl
		       or
	       perl Makefile.PL	LIB=C:/Perl/Site/Lib

       If, like	me, you	don't have permission to write man pages into unix
       system directories, use:

	       make pure_install

       instead of make install.	This option is secreted	in the middle of p 414
       of the second edition of	the dromedary book.

WARNING	re CVS bugs
       The following are my ideas as to	what constitutes a bug in CVS:

       o   The initial revision	tag, supplied when populating the repository
	   with	'cvs import', is not saved into	$CVSROOT/CVSROOT/val-tags.

       o   The 'cvs tag' command does not always put the tag into 'val-tags'.

       o   'cvs	checkout -dNameOfDir' fails if NameOfDir =~ /\/$/.

       o   'cvs	checkout -d NameOfDir' inserts a leading space into the	name
	   of the directory it creates.

WARNING	re test	environment
       This code has only been tested under Unix. Sorry.

WARNING	re project names 'v' directory names
       I assume	your copy of the repository was	checked	out into a directory
       with the	same name as the project, since	I do a 'cd $HOME/$project'
       before running 'cvs status', to see if your copy	is up-to-date. This is
       because some activity is	forbibben unless your copy is up-to-date.
       Typical cases of	this include:

       o   "checkOut"

       o   "removeDirectory"

       o   "setTag"

WARNING	re shell intervention
       Some commands cause the shell to	become involved, which,	under Unix,
       will read your .cshrc or	whatever, which	in turn	may set	CVSROOT	to
       something other than what you set it to before running your script. If
       this happens, panic...

       Actually, I think I've eliminated such cases. You hope so.

WARNING	re Perl	bug
       As always, be aware that	these 2	lines mean the same thing, sometimes:

       o   $self -> {'thing'}

       o   $self->{'thing'}

       The problem is the spaces around	the ->.	Inside double quotes, "...",
       the first space stops the dereference taking place. Outside double
       quotes the scanner correctly associates the $self token with the
       {'thing'} token.

       I regard	this as	a bug.

addDirectory($dir, $subDir, $message)
       Add an existing directory to the	project.

       $dir can	be a full path,	or relative to the CWD.

addFile($dir, $file, $message)
       Add an existing file to the project.

       $dir can	be a full path,	or relative to the CWD.

checkOut($readOnly, $tag, $dir)
       Prepare & perform 'cvs checkout'.

       You call	checkOut, and it calls _checkOutDontCallMe.

       o   $readOnly ==	0 -> Check out files as	read-write.

       o   $readOnly ==	1 -> Check out files as	read-only.

       o   $tag	is Null	-> Do not call upToDate; ie check out repository as
	   is.

       o   $tag	is not Null -> Call upToDate; Croak if repository is not up-
	   to-date.

       The value of $raw used in the call to new influences the	handling of
       $tag:

       o   $raw	== 1 ->	Your tag is passed as is to CVS.

       o   $raw	== 0 ->	Your tag is assumed to be of the form release_1.23,
	   and is converted to CVS's form release_1_23.

       $dir can	be a full path,	or relative to the CWD.

commit($message)
       Commit changes.

       Called as appropriate by	addFile, removeFile and	removeDirectory, so
       you don't need to call it.

createRepository()
       Create a	repository, using the current $CVSROOT.

       This involves creating these files:

       o   $ENV{'CVSROOT'}/CVSROOT/modules

       o   $ENV{'CVSROOT'}/CVSROOT/val-tags

       o   $ENV{'CVSROOT'}/CVSROOT/history

       Notes:

       o   The 'modules' file contains these lines:

		   CVSROOT  CVSROOT
		   modules  CVSROOT  modules
		   $self -> {'project'}	 $self -> {'project'}

	   where $self -> {'project'} comes from the 'project' parameter to
	   new()

       o   The 'val-tags' file is initially empty

       o   The 'history' file is only created if the 'history' parameter to
	   new() is set.  The file is initially	empty

getTags()
       Return a	reference to a list of tags.

       See also: the $raw option to new().

       "getTags" does not take a project name because tags belong to the
       repository as a whole, not to a project.

history({})
       Report details from the history log, $CVSROOT/CVSROOT/history.

       You must	have used new({'history' => 1}), or some other mechanism, to
       create the history file,	before CVS starts logging changes into the
       history file.

       The anonymous hash takes	any parameters 'cvs history' takes, and	joins
       them with a single space. Eg:

	       $cvs -> history();

	       $cvs -> history({'-e' =>	''});

	       $cvs -> history({'-xARM'	=> ''});

	       $cvs -> history({'-u' =>	$ENV{'LOGNAME'}, '-x' => 'A'});

       but not

	       $cvs -> history({'-xA' => 'M'});

       because it doesn't work.

new({})
       Create a	new object. See	the synopsis.

       The anonymous hash takes	these parameters, of which 'project' is	the
       only required one.

       o   'project' =>	'killerApp'. The required name of the project. No
	   default

       o   'permissions' => 0775. Unix-specific	stuff. Default.	Do not use
	   '0775'.

       o   'history' =>	0. Do not create $CVSROOT/CVSROOT/history when
	   createRepository() is called. Default

       o   'history' =>	1. Create $CVSROOT/CVSROOT/history, which initiates
	   'cvs	history' stuff

       o   'raw' => 0. Convert tags from CVS format to real format. Eg:
	   release_1.23. Default.

       o   'raw' => 1. Return tags in raw CVS format. Eg: release_1_23.

       o   'verbose' =>	0. Do not report on the	progress of mkpath/rmtree

       o   'verbose' =>	1. Report on the progress of mkpath/rmtree. Default

populate($sourceDir, $vendorTag, $releaseTag, $message)
       Import an existing directory structure. But, (sub) import is a reserved
       word.

       Use this	to populate a repository for the first time.

       The value used for $vendorTag is	not important; CVS discards it.

       The value used to $releaseTag is	important; CVS discards	it (why?) but
       I force it to be	the first tag in $CVSROOT/CVSROOT/val-tags. Thus you
       should supply a meaningful value. Thus 'release_0_00' is	strongly,
       repeat strongly,	recommended.

       The value of $raw used in the call to new influences the	handling of
       $tag:

       o   $raw	== 1 ->	Your tag is passed as is to CVS.

       o   $raw	== 0 ->	Your tag is assumed to be of the form release_1.23,
	   and is converted to CVS's form release_1_23.

removeDirectory($dir)
       Remove a	directory from the project.

       This deletes the	directory (and all its files) from your	working	copy
       of the repository, as well as deleting them from	the repository.

       Warning:	$dir will have $CVSROOT	and $HOME prepended by this code.  Ie:
       $dir starts from	- but excludes - your home directory (assuming,	of
       course, you've checked out into your home directory...).

       You can't remove	the current directory, or a parent.

removeFile($dir, $file,	$message)
       Remove a	file from the project.

       This deletes the	file from your working copy of the repository, as well
       as deleting it from the repository.

       $dir can	be a full path,	or relative to the CWD.	 $file is relative to
       $dir.

runOrCroak()
       The standard way	to run a system	command	and report on the result.

setTag($tag)
       Tag the repository.

       You call	setTag,	and it calls _setTag.

       The value of $raw used in the call to new influences the	handling of
       $tag:

       o   $raw	== 1 ->	Your tag is passed as is to CVS.

       o   $raw	== 0 ->	Your tag is assumed to be of the form release_1.23,
	   and is converted to CVS's form release_1_23.

stripCVSDirs($dir)
       Delete all CVS directories and files from a copy	of the repository.

       Each user directory contains a CVS sub-directory, which holds 3 files:

       o   Entries

       o   Repository

       o   Root

       Zap 'em.

status()
       Run cvs status.

       Return a	reference to a list of lines.

       Only called by upToDate(), but you may call it.

update($noChange)
       Run 'cvs	"-q" ["-n"] update', returning a reference to a	list of	lines.
       Each line will start with one of	[UARMC?], as per the CVS docs.

       $cvs -> update(1) is a good way to get a	list of	uncommited changes,
       etc.

       o   $noChange ==	0 -> Do	not add	"-n" to	the cvs	command. Ie update
	   your	working	copy

       o   $noChange ==	1 -> Add "-n" to the cvs command. Do not change	any
	   files

upToDate()
       o   return == 0 -> Repository not up-to-date.

       o   return == 1 -> Up-to-date.

_checkOutDontCallMe($readOnly, $tag, $dir)
       Checkout	a current copy of the project.

       You call	checkOut, and it calls this.

       o   $readOnly ==	0 -> Check out files as	read-write.

       o   $readOnly ==	1 -> Check out files as	read-only.

_fixTag($tag)
       Fix a tag which CVS failed to add.

       Warning:	$tag must be in	CVS format: release_1_23, not release_1.23.

_mkpathOrCroak($self, $dir)
       There is	no need	for you	to call	this.

_readFile($file)
       Return a	reference to a list of lines.

       There is	no need	for you	to call	this.

_setTag($tag)
       Tag the current version of the project.

       Warning:	$tag must be in	CVS format: release_1_23, not release_1.23.

       You call	setTag and it calls this.

_validateObject($tag, $file, $mustBeAbsent)
       Validate	an entry in one	of the CVS files 'module' or 'val-tags'.

       Warning:	$tag must be in	CVS format: release_1_23, not release_1.23.

AUTHOR
       "VCS::CVS" was written by Ron Savage _ron@savage.net.au_	in 1998.

LICENCE
       Australian copyright (c)	1998-2002 Ron Savage.

	       All Programs of mine are	'OSI Certified Open Source Software';
	       you can redistribute them and/or	modify them under the terms of
	       The Artistic License, a copy of which is	available at:
	       http://www.opensource.org/licenses/index.html

perl v5.32.1			  2022-03-28			   VCS::CVS(3)

NAME | SYNOPSIS | DESCRIPTION | INSTALLATION | WARNING re CVS bugs | WARNING re test environment | WARNING re project names 'v' directory names | WARNING re shell intervention | WARNING re Perl bug | addDirectory($dir, $subDir, $message) | addFile($dir, $file, $message) | checkOut($readOnly, $tag, $dir) | commit($message) | createRepository() | getTags() | history({}) | new({}) | populate($sourceDir, $vendorTag, $releaseTag, $message) | removeDirectory($dir) | removeFile($dir, $file, $message) | runOrCroak() | setTag($tag) | stripCVSDirs($dir) | status() | update($noChange) | upToDate() | AUTHOR | LICENCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VCS::CVS&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help