Draft LibCVS API

This document is a draft. It will change, perhaps a lot. Feeback of any kind is happily received.

Introduction

Purpose

The purpose of LibCVS is to provide access to CVS working directories and repositories through a library interface. This document describes the LibCVS API in a language-independent fashion, which can then be implemented natively in many languages. This API strives present the best solution to the problem of accessing repositories and working directories. As we learn from implementing and using the API, this document will be updated to reflect the new understanding. Its longer term goal is to expand beyond CVS, and present an interface for the more general problem space of version control.

Currently the document describes a read-only API. Specifically, it doesn't specify how to checkout or update to working directories, or commit or tag to the repository.

This is an object-oriented API. However, it is desirable that non-OO languages (notably C), be able to implement it cleanly and without significant effort. To this end, it avoids heavy use of polymorphism and inheritance.

Implementing the API

Changes will have to be made to the API when implementing it. Notably, class and method names should be changed to match language conventions. For example, in Java, it will be desirable to add "get" to the beginning of many of the method names. Classnames can also be expected to change, Branch would become VCS::LibCVS::Branch in Perl, and org.libcvs.Branch in Java.

If an implemention requires or would be eased by a major change to the interface, then that change should be discussed and propagated back to this document.

Although it is not listed, it can be useful for many of these objects to define a boolean method equals() which can determine if two objects of the same type are equal. Implementation of this is left to each language, although it might be useful to add it.

Summary of Objects

The objects of LibCVS are split into three broad groups: those used to access the repository, those used to access working directories (sandboxes), and support objects used for both purposes.

Examples

Here are a couple of brief examples, just to get an idea of how to use the interface.

Listing Files in the Repository

Repository repo = new Repository(":ext:user@host.example.com/var/cvs")
Directory dir = new Directory(repo, "module")
File[] files = dir.getFiles()
for (i = 0; i < files.length; i++ ) {
    print files[i].name()
}

Listing Files in a Working Directory

WorkingDirectory wDir = new WorkingDirectory("/home/user/sandbox")
WorkingFile[] wFiles = wDir.getFiles()
for (i = 0; i < wFiles.length; i++ ) {
    print wFiles[i].name()
}

Shared Classes

These classes are used both when accessing working directories, and accessing repositories. The majority of these classes are subclasses of Datum, used primarily for encapsulating data.

Repository

The Repository object is used as the starting point for an interaction when no working directory is present. It is also used internally for connecting to the repository. It has the following methods:

Repository new(string root)

DatumRoot root()

string version()

Datum

Datum (the singular of Data) is a superclass for several data-wrapping classes. Depending on language convention, its subclasses can provide their data either as public accessible members, or through methods. It also defines two methods which subclasses are expected to implement.

The user of LibCVS will generally use Datum objects just for reading information. There should be no need for them to construct these objects.

There are several more subclasses of Datum used internally by LibCVS, but are not part of the public API.

string asString()

boolean equals(Datum d)

DatumFileContents

Superclass: Datum

A datum containing the contents of a file. It has the following data members:

DatumNumber

Superclass: Datum

A datum containing a revision number. It can represent a regular revision number ("1.1"), a branch number ("1.1.2") or magic branch number("1.1.0.2"). In general this class should be primarily internal. Users of the library may need to print out values and create new ones from user supplied information, but branch traversal should usually use the methods of FileRevision and FileBranch.

Some revision number methods are branch or revision specific, these methods have been split off into subclasses. Optionally, all methods could be rolled into a single class, and modified to raise errors if they are called inappropriately. If this is done, an additional method boolean isBranch() would have to be added.

To describe the relationship among both revision and branch revision numbers, the terms ancestor and descendant are used. The ancestral relationship is transitive, so if a is an ancestor of b, and b is an ancestor of c, then it follows that a is an ancestor of c. A revision revision number is an ancestor of all revision numbers that follow it on its branch. A branch revision number is a descendant of its base revision, and an ancestor of all other revisions on that branch. Revisions which don't have an ancestral relationship are called incomparable. Descendant is the opposite of ancestor, so if a is an ancestor of b, then b is a descendant of a.

Thus "1.6" is an ancestor of "1.9", "1.6.2", "1.6.2.5" and "1.19.14.4"; "1.6.2" is an ancestor of "1.6.2.5" and a descendant of "1.6"; and "1.6.2.5" and "1.19" are incomparable.

Because of CVS's lazy branching scheme, branches that sprout from the same revision could be ancestors. The terms possible ancestor and possible descendant are used to describe this relationship. For example, "1.6.2" is a possible ancestor of "1.6.4".

It has the following data member:

and some methods:

RevisionNumber new(string number)

enum compare(DatumNumber other)

DatumBranchNumber

Superclass: DatumNumber

A branch revision number, with the following additional methods:

boolean isTrunk()

boolean isImportBranch()

DatumRevisionNumber base()

DatumRevisionNumber firstRevision()

DatumRevisionNumber

Superclass: DatumNumber

A revision revision number, with the following additional methods:

DatumBranchNumber branch()

DatumNumber predecessor()

DatumNumber successor()

DatumRoot

Superclass: Datum

A datum containing a CVSROOT specification, for contacting a repository. It has the following data members:

Repository Classes

These objects represent the contents of the repository. They do not require, nor refer to checked-out files or local administration files. They are named with filesystem names, relative to the root of the repository.

FileOrDirectory

A FileOrDirectory is a superclass which is not used directly. It's not called RevisionedObject because directories aren't Revisioned.

static FileOrDirectory find(Repository r, string Name)

string name()

Repository repository()

Directory directory()

Directory

Superclass: FileOrDirectory

The top level repository directory is denoted by ".".

Directory[] directories()

Directory directory(string name)

File[] files()

File file(string name)

File

A file in the repository. It encompasses all revisions on all branches of that file. Essentially, this is everything in the ,v file.

FileBranch[] branches()

FileBranch branch(string name)

FileBranch branch(DatumNumber rn)

FileBranch branch(Branch branch)

FileRevision revision(DatumNumber rn)

string[] tags()

DirectoryBranch

A directory as seen from a branch. From this class you can get all of the files which are on a specific branch, rather than all the files that exist in the repository. In CVS terms this is a rather artificial construction, since CVS neither revisions nor branches directories.

Directory directory()

Branch branch()

FileBranch[] fileBranches()

FileBranch

A single branch of a single file. It has a branch name, which is shared with FileBranches for other files, as well as a revision number which is specific to this file.

DatumBranchNumber revisionNumber()

File file()

Branch branch()

FileRevision tipRevision()

FileRevision firstRevision()

FileRevision revision(time t)

boolean isTrunk()

FileBranch parent()

boolean precedes(FileBranch other)

FileRevision

One revision of a particular file, identified by a revision number. It remembers which branch it's on, so that successor and predecessor can be used effectively to traverse the branch. This is necessary because the base revision of a branch is on that branch.

DatumRevisionNumber revisionNumber()

File file()

FileBranch fileBranch()

string logMessage()

string committer()

time time()

boolean isDead()

DatumFileContents contents()

FileRevision predecessor()

FileRevision successor()

enum compare(FileRevision)

Branch

A named branch across the entire repository. It is a collection of specific numbered branches for multiple files, all of which share a name.

string name()

FileBranch[] fileBranches()

Working Directory Classes

Objects which represent the state of a CVS working directory or sandbox. The working directory can be traversed using these objects.

WorkingFileOrDirectory

A parent class for local directories or files.

string name()

Repository repository()

FileOrDirectory repositoryObject()

Branch branch()

WorkingDirectory

Superclass: WorkingFileOrDirectory

WorkingDirectory new(string name)

WorkingFile[] files()

DirectoryBranch directoryBranch()

WorkingUnmanagedFile[] unmanagedFiles()

WorkingUnmanagedDirectory[] unmanagedDirectories()

WorkingDirectory[] directories()

string[] ignoredFiles

string[] ignoredDirectories

WorkingFile

Superclass: WorkingFileOrDirectory

A file in the working directory managed by CVS.

In a way, a WorkingFile is just a special sort of FileRevision. Could this viewpoint be useful to the interface?

WorkingFile new(string name)

FileBranch fileBranch()

FileRevision fileRevision()

WorkingDirectory directory()

enum scheduledAction()

enum state()

enum repositoryState()

DatumRevisionNumber revisionNumber()

DatumFileContents fileContents()

WorkingUnmanagedFile

Superclass: WorkingFileOrDirectory

A file in a CVS working directory, which is neither managed by nor ignored by CVS.

boolean isInTheWay()

DatumFileContents fileContents()

WorkingUnmanagedDirectory

Superclass: WorkingFileOrDirectory

A directory in a CVS working directory, which is neither managed by nor ignored by CVS.

boolean isInTheWay()