Java RCS

RCS is a version control system that offers users (programmers) the ability to archive older version of files in a repository. They have to ability to safely retrieve the older versions of files. This comes out handy in multi-user situations because the code is centralized. RCS is quite an old technology dating back since 1982. There are many programs out there that implement this file format. CVS is a technology that is built from RCS technology.

1.2 Goals

This project has 2 goals. The first one is to implement the RCS functions in Java. From that point on the Java API can be used to communicate with the RCS repository. A command line interface will be created that will allow users to execute RCS commands. The second goal is to provide a Java API that will aid in the development of CVS.

1.3 Customers

Java Developers and programmers in general that want to use the RCS Version control system.

1.4 Team Participants

People involved at source forge.

2 Overview

2.1 Scope

The scope involves developing a system that allows users to perform rcs operations (see glossary).

2.2 Assumptions

All items are available at this time

2.3 Risks

2.4 Dependencies

No Dependencies.

3 Functional Requirements

3.1 System Functions

3.1.1 Basic Functions

Number	Requirement	Category
	Store and retrieve multiple revisions of text. RCS saves all old revisions in a space efficient way. Changes no longer destroy the original, because the previous revisions remain accessible. Revisions can be retrieved according to ranges of revision numbers, symbolic names, dates, authors, and states.
	Maintain a complete history of changes. RCS logs all changes automatically. Besides the text of each revision, RCS stores the author, the date and time of check-in, and a log message summarizing the change. The logging makes it easy to find out what happened to a module, without having to compare source listings or having to track down colleagues.
	Resolve access conflicts. When two or more programmers wish to modify the same revision, RCS alerts the programmers and pre vents one modification from corrupting the other.
	Maintain a tree of revisions. RCS can maintain separate lines of development for each module. It stores a tree structure that represents the ancestral relationships among revisions.
	Merge revisions and resolve conflicts. Two separate lines of development of a module can be coalesced by merging. If the revisions to be merged affect the same sections of code, RCS alerts the user about the overlapping changes.
	Control releases and configurations. Revisions can be assigned symbolic names and marked as released, stable, experimental, etc. With these facilities, configurations of modules can be described simply and directly.
	Automatically identify each revision with name, revision number, creation time, author, etc. The identification is like a stamp that can be embedded at an appropriate place in the text of a revision. The identification makes it simple to determine which revisions of which modules make up a given configuration.
	Minimize secondary storage. RCS needs little extra space for the revisions (only the differences). If intermediate revisions are deleted, the corresponding deltas are compressed accordingly.
1.5	Allow users to check the status of a file in the repository. The requested information will be returned to the user visually.
1.6	Allow users to conduct administrative operations with files in the repository. Any administrative changes on a file will appear in the file entry in the repository.

3.1.2 Repository Requirements

Number	Requirement	Category
2.1	Repository will be stored on the local machine’s file system.
2.2	Repository will follow the RCS repository standard. Please refer to appendix A for more information.
2.3	Repository access should be quick.
	Repository should be able to handle both ANSII and binary data files.
	The repository will be composed of “,v” files. “,v” files contain the data to the versioned file and all history of changes along with dates, and version numbers.
2.4	Each file entry will have a corresponding “,v” file.
2.5	The first part that precedes the “,v” will be the file name of the original file that was checked-in. Example: autoexec.bat will be called “autoexec.bat,v” in the repository.
2.6	All date and time that will be recorded in the “,v” files will be GMT.

3.1.3 Initial System Configuration Requirements

Number	Requirement	Category
3.1	The username and repository location will be stored in a configuration file that will be loaded on each RCS command execution.

3.1.4 Check-in Requirements

Number	Requirement	Category
3.1	Stores new revisions into RCS files.
3.2	System will read the information from the file and create a proper entry into the versioned file.
3.3	For the system to accept the checked-in file the callers login must be on the files access list, or the access list must be empty.
3.4	To append a new revision to an existing branch, the tip revision on that branch must be locked by the caller. Otherwise, only a new branch can be created.
3.5	For each revision deposited, the system prompts for a log message. The log message should summarize the change and must be terminated by end-of-file or by a line containing “.” by itself.
3.6	If several files are checked in the system asks whether to reuse the previous log message.
3.7	If the standard input is not a terminal, the system suppresses the prompt and uses the same log message for all files.
3.8	If the RCS file does not exist, the system creates it and deposits the contents of the working file as the initial revision (default number: 1.1). The access list is initialized to empty. Instead of the log message, the system requests descriptive text
3.9	If rev begins with a period, then the default branch (normally the trunk) is prepended to it. If rev is a branch number followed by a period, then the latest revision on that branch is used.
3.10	If rev is a revision number, it must be higher than the latest one on the branch to which rev belongs, or must start a new branch.
3.11	If rev is a branch rather than a revision number, the new revision is appended to that branch. The level number is obtained by incrementing the tip revision number of that branch. If rev indicates a non-existing branch, that branch is created with the initial revision numbered rev.1.
3.12	If rev is omitted, the system tries to derive the new revision number from the caller's last lock. If the caller has locked the tip revision of a branch, the new revision is appended to that branch. The new revision number is obtained by incrementing the tip revision number. If the caller locked a non-tip revision, a new branch is started at that revision by incrementing the highest branch number at that revision. The default initial branch and level numbers are 1.
3.13	If rev is omitted and the caller has no lock, but owns the file and locking is not set to strict, then the revision is appended to the default branch
3.15	The Diff algorithm must be optimized for performance.
3.16	If only a working file is given, the system tries to find the corresponding RCS file in an RCS subdirectory and then in the working file's directory.

3.1.5 Checkout Requirements

Number	Requirement	Category
4.1	Users should have the ability to retrieve any specified revision from the RCS file.
4.2	Users should be able to lock files at the same time they are retrieving them.
4.3	Users should have to ability to overwrite the working file upon giving a special command.
4.4	Users should be able to unlock files at the same time they are retrieving them.
4.5	Users should be able to retrive the specified file to standard output.
4.6	Users should be able to retrive versions by specifying a date.
4.7	Retrieves a revision from each RCS file and stores it into the corresponding working file. A revision is selected by options for revision or branch number, check-in date/time, author, or state.
2.2	When the selection options are applied in combination, the system retrieves the latest revision that satisfies all of them. If none of the selection options is specified, the system retrieves the latest revision on the default branch.
2.3	The checkout command applied to an RCS file with no revisions creates a zero-length working file.
2.4	The working file inherits the read and execute permissions from the RCS file. In addition, the owner write permission is turned on, unless some option is set or the file is checked out unlocked and locking is set to strict.
2.5	If a file with the name of the working file exists already and has write permission, co aborts the checkout, asking beforehand if possible. If the existing working file is not write-able or -f is given, the working file is deleted without asking.
2.6	On an error which prevented checking out the file, either print a nonfatal error and return 1, or give a fatal error. On success, return 0.
	REV is the numeric revision to check out. It may be NULL, which means to check out the head of the default branch.
	If WORKFILE is not NULL, check out the revision to WORKFILE.
	Otherwise, if WORKFILE is NULL, check out the revision to SOUT.

3.1.6 File Administrative Requirements

Number	Requirement	Category
	When issuing a "-i" switch the system will create and initialize a new RCS file, but will not deposit any revision. If the RCS file has no path prefix, try to place it first into the subdirectory ./RCS, and then into the current directory. If the RCS file already exists, print an error message.
2.1	Upon request the system will append the login names appearing in the comma-separated list logins to the access list of the RCS file.
2.2	System will have the ability to add the access list of another file to the existing file.
2.3	System will have the ability to remove the names from the access list of an RCS file.
2.4	The system should be built in a way that allows for future changes to the RCS file format.

3.2 Use Case Diagram

See Use Case Diagram

3.3 Use Cases

3.3.1 Check-in

Use Case:	Check in a File
Actors	User, System
Purpose	To check-in an RCS revisions into the repository.
Overview
Reference

Typical Course of Events
User	System
This use case begins when a user issues the check in command with a file specified as one of the perimeters.	System responds by checking to see if the file exists and that it is readable.
	System will read the data from the file compute the diffs if necessary and write the data into an RCS file.
	System will delete the file from the users directory. (Check options)
	System will indicate success (0) or failure(1)

Use Case:	Check out a file
Actors	User, System
Purpose	Check out a revision from the repository.
Overview
Reference

Typical Course of Events
User	System
This use case begins when a user issues a check out command with a file specified as one of the perimeters.	System will check to see if file exists in the system
	Systems will checkout the data of the file into the users file system or standard output.
	System will indicate success (0) or failure(1)

Use Case:	Diff file
Actors	User, System
Purpose	Compares RCS revisions
Overview	rcsdiff runs diff(1) to compare two revisions of each RCS file given.
Reference

Use Case:	Change file attribute
Actors	User
Purpose	Change RCS file attributes.
Overview	Creates new RCS files or changes attributes of existing ones. An RCS file contains multiple revisions of text, an access list, a change log, descriptive text, and some control attributes.
Reference

Use Case:	Clean working file
Actors	User
Purpose	Cleans files that are not being worked on.
Overview	Removes files from the file system that are not being worked on.
Reference

Use Case:	Merge revision
Actors	User
Purpose	Incorporates the changes between two revisions of an RCS file into the corresponding working file.
Overview
Reference

Use Case:	Print info
Actors	User
Purpose	Prints information about RCS files.
Overview	Prints the following information for each RCS file: RCS pathname, working pathname, head (i.e., the number of the latest revision on the trunk), default branch, access list, locks, symbolic names, suffix, total number of revisions, number of revisions selected for printing, and descriptive text. This is followed by entries for the selected revisions in reverse chronological order for each branch. For each revision, This prints revision number, author, date/time, state, number of lines added/deleted (with respect to the previous revision), locker of the revision (if any), and log message. All times are displayed in Coordinated Universal Time (UTC) by default; this can be overridden with -z.
Reference

3.4 Draft collaboration Diagram

See Collaboration Diagram.

4 Non-Functional Requirements

5 Appendix

5.1 Appendix A (RCS File System Definition)

5.1.1 DESCRIPTION

       An RCS file's contents are described by the grammar below.

       The text is free format: space, backspace,  tab,  newline,

       vertical  tab,  form  feed,  and  carriage return (collec-

       tively,        white  space)  have  no  significance  except  in

       strings.  However, white space cannot appear within an id,

       num, or sym, and an RCS file must end with a newline.

       Strings are enclosed by @.  If a string contains a  @,  it

       must  be doubled; otherwise, strings can contain arbitrary

       binary data.

       The meta syntax uses the following conventions: `|'  (bar)

       separates  alternatives;  `{'  and  `}'        enclose  optional

       phrases; `{' and `}*' enclose phrases that can be repeated

       zero or more times; `{' and '}+' enclose phrases that must

       appear at least once and can be repeated; Terminal symbols

       are in boldface; nonterminal symbols are in italics.

       rcstext  ::=  admin {delta}* desc {deltatext}*

       admin         ::=  head     {num};

                  { branch     {num}; }

                  access   {id}*;

                  symbols  {sym : num}*;

                  locks    {id : num}*;  {strict ;}

                  { comment  {string}; }

                  { expand     {string}; }

                  { newphrase }*

       delta         ::=  num

                  date     num;

                  author   id;

                  state    {id};

                  branches     {num}*;

                  next     {num};

                  { newphrase }*

       desc  ::=  desc    string

       deltatext ::=  num

                  log      string

                  { newphrase }*

                  text     string

       num   ::=  {digit | .}+

       digit         ::=  0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

       id    ::=  {num} idchar {idchar | num}*

       word  ::=  id | num | string | :

       Identifiers  are  case  sensitive.   Keywords are in lower

       case only.  The sets of keywords and identifiers can over-

       lap.   In most environments RCS uses the ISO 8859/1 encod-

       ing: visible graphic  characters  are  codes  041-176  and

       240-377,  and white space characters are codes 010-015 and

       040.

       Dates, which appear after the date  keyword,  are  of  the

       form  Y.mm.dd.hh.mm.ss,        where Y is the year, mm the month

       (01-12), dd the day (01-31), hh the hour (00-23),  mm  the

       minute  (00-59),  and  ss  the second (00-60).  Y contains

       just the last two digits of the year for years  from  1900

       through        1999,  and  all  the  digits of years thereafter.

       Dates use the Gregorian calendar; times use UTC.

       The newphrase productions in the grammar are reserved  for

       future  extensions  to  the  format of RCS files.  No new-

       phrase will begin with any keyword already in use.

       The delta nodes form a tree.  All nodes whose numbers con-

       sist  of a single pair (e.g., 2.3, 2.1, 1.3, etc.)  are on

       the trunk, and are linked through the next field in  order

       of  decreasing  numbers.  The head field in the admin node

       points to the head of that sequence  (i.e.,  contains  the

       highest        pair).       The  branch node in the admin node indi-

       cates the default branch (or revision) for most RCS opera-

       tions.  If empty, the default branch is the highest branch

       on the trunk.

       All delta nodes whose numbers consist of 2n fields  (n>=2)

       (e.g.,  3.1.1.1,  2.1.2.2,  etc.)   are linked as follows.

       All nodes whose first 2n-1 number fields are identical are

       linked  through the next field in order of increasing num-

       bers.  For each such sequence, the delta node whose number

       is identical to the first 2n-2 number fields of the deltas

       on that sequence is called the branch point.  The  branches

       field  of  a  node  contains  a list of the numbers of the

       first nodes of all sequences for which  it  is  a  branch-

       point.  This list is ordered in increasing numbers.

6 Glossary

Term

rcs operations

Check in, check out, diff, change file attribute, clean working file, merge, and print rcs log message.

Get revision number if it wasn't passed in.