Go to the first, previous, next, last section, table of contents.


3 Basic Use

For an overview of the entire process of project source-code maintenance with PRCS, read the sections below in order. It uses a continuing example of a project called P1.

Creating a repository

Before you can use PRCS at all, you must establish a PRCS repository (a directory). PRCS will create and initialize the repository if it does not exist the first time you attempt to use it. PRCS takes the name of the repository from the environment variable PRCS_REPOSITORY, which must be defined before running PRCS (if undefined, it defaults to `$HOME/PRCS').

For example, to have a repository named `PRCS_FILES' in your home directory, execute

% setenv PRCS_REPOSITORY ~/PRCS_FILES

in the C-shell or

$ export PRCS_REPOSITORY
$ PRCS_REPOSITORY=${HOME}/PRCS_FILES

in the Bourne shell. You may want to put this command into your .cshrc or .profile initialization file. In the rest of this document, we will assume that PRCS_REPOSITORY is properly defined.

When you first run PRCS after having set this environment variable, it will create directory `PRCS_FILES' in your home directory, assuming it does not already exist. If you attempt to run PRCS with PRCS_REPOSITORY set to a directory not in the right format, it will report an error.

Once your repository is established, you should generally be careful not to modify it except through PRCS, except that changing the group, protections, or name of the repository is harmless.

Starting a new project

To create the first version of a completely new project named P1, go to the desired working directory and use the following command:

% prcs checkout P1

Assuming there is no prior project P1, the only result of this command is to create a working file `P1.prj' in the current directory; the projects directory and its contents are not modified. In `P1.prj', you will initially find the following lines:

;; -*- Lisp -*-
(Created-By-Prcs-Version 1 1 0)
(Project-Description "")
(Project-Version P1 0 0)
(Parent-Version -*- -*- -*-)
(Version-Log "Empty project.")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 01:54:11 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Project-Keywords)
(Files
; This is a comment.  Fill in files here.
; For example:  (prcs/checkout.cc ())
)
(Merge-Parents)
(New-Merge-Parents)

The second line identifies the project version from which these files came: in this case from a version 0.0 of the project named P1. Minor version 0 exists implicitly for every major version of a project; it is empty, containing no files and a standard project descriptor, as shown above. The third line indicates the (in this case, nonexistent) version from which version 0.0 was derived.

Adding files to a project

When you create working files, say main.c and doc/foobar.1, you can add them to the version of P1 you are creating by editing the Files entry of `P1.prj' to look like this:

(Files
  (main.c ())
  (doc/foobar.1 ())
)

The Files list identifies the names of the files as they appear relative to the working directory in which you start. The empty lists after each name contain information indicating where these files came from in the repository; since these are new files, the lists are empty to indicate that your files did not come from the repository, but are new. The information in these lists has a format internal to PRCS, and you need not worry about it. Even though the project descriptor `P1.prj' itself is not explicitly listed in the Files list, it is implicitly considered one of the files in the project.

When you have many files to add to the Files list--as for example when you have an existing directory structure full of files that you wish to bring under version control--it is inconvenient to do so by hand. PRCS can add them for you automatically with the command

% prcs populate P1

which finds all files in the current directory and its subdirectories and adds them to the Files list in `P1.prj'. At this point, you can edit `P1.prj' to remove files that you don't want to save (e.g., compiled object files or backup files).

Adding version commentary

It is a good idea at this point to add some commentary to the `.prj' file before check-in:

(Project-Description "Sample PRCS Project")
(New-Version-Log "checkin main.c and doc/foobar.1")

The Project-Description information, by default, is carried over from version to version of a project (so that you usually won't change it after the first version). The New-Version-Log becomes the Version-Log upon check-in and any old version log from a prior version is deleted. Thus, you may use the Version-Log entries of the checked-in versions for any notes about the reasons for the new version or its contents. You can use newlines in the string constants used to hold the commentary, and make them arbitrarily long. See section 2 Definitions.

Checking in a version

To check in a new project version of project P1, use the command

% prcs checkin P1

If there is only one `.prj' file in the current directory, you may even leave off the P1 argument. This command looks at the file `P1.prj' to find out the major version of P1 from which the current working files were copied and adds a new minor version to it. In this case, since `P1.prj' records no major version name, PRCS uses the default major version name, `0'. Thus, this check-in will create version 0.1 (minor version 1 of major version 0) of P1. The command prcs checkin modifies `P1.prj', before checking it in, to look something like this:

;; -*- Lisp -*-
(Created-By-Prcs-Version 0 13 8)
(Project-Description "Sample PRCS Project")
(Project-Version P1 0 1)
(Parent-Version P1 0 0)
(Version-Log "checkin main.c and doc/foobar.1")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 02:10:24 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Files
  (main.c (P1/0_main.c 1.1 644))
  (doc/foobar.1 (P1/0_foobar.1 1.1 644))
)
(Merge-Parents)
(New-Merge-Parents)

As you can see, PRCS has added the version identification, a timestamp, a record of the account performing the checkin, and some internal identification information about the two files now in the project. It has also changed the New-Version-Log declaration to the Version-Log (which is removed when you modify this version and check-in a new one).

Your working directory now contains copies of the files in version 0.1 of P1. You might now add a new working file, say `header.h', and modify `main.c'. You add the line

  (header.h ())

to the Files list. You will also want to create a New-Version-Log entry and perform another checkin. The new version (0.2) of `P1.prj' might now contain

;; -*- Lisp -*-
(Created-By-Prcs-Version 0 13 8)
(Project-Description "Sample PRCS Project")
(Project-Version P1 0 2)
(Parent-Version P1 0 1)
(Version-Log "")
(New-Version-Log "")
(Checkin-Time "Sun, 31 Dec 1995 02:13:00 -0700")
(Checkin-Login jmacd)
(Populate-Ignore ())
(Files
  (main.c (P1/0_main.c 1.2 644))
  (doc/foobar.1 (P1/0_foobar.1 1.1 644))
  (header.h (P1/0_header.h 1.1 644))
)
(Merge-Parents)
(New-Merge-Parents)

The files of version 0.2 of P1 have now been saved; you may destroy the working directory and later restore it with prcs checkout.

It is not necessary to check in all your working files. By providing a list of files and directories after the project specifier, you can limit the working files considered to those listed:

% prcs checkin P1 doc

copies only the working files in doc into the new version of P1; for other files listed in `P1.prj', PRCS uses the versions identified by the internal file identifiers in the Files list of `P1.prj'. Thus, if these identifiers are unchanged in your working `P1.prj' file since it was checked out, the same files versions that they identify will be used in the new version of P1 (the working versions, however, may differ in the values of certain keywords. See section 9 Keywords.)

Checking out a version

The command prcs checkout creates working copies of the files (and directories) in a project version, usually rooted in the current working directory. For example,

% prcs checkout -r0.1 P1

checks out version 0.1 (minor version 1 of major version 0) of project P1, creating the subdirectory doc, if needed. If you didn't specify a major version name when you created the project it defaulted to '0' and this is the initial version with no files. You needn't be quite so specific in specifying the version:

% prcs checkout -r1 P1

or

% prcs checkout -r1.@ P1

checks out the latest minor version of major version 1 of P1. If you use only numerals for your major versions, you may even leave off the -r altogether to get the latest version checked into the repository.

It is not necessary to check out an entire version at once; you may specify selected directories or files instead. For example

% prcs checkout -r0.2 P1 main.c header.h

checks out just the file main.c from version 0.2 of P1, and

% prcs checkout -r0.1 P1 doc

checks out the doc directory (and all files contained in and below it) from version 0.1 of P1.

Comparing versions

If you have modified a working file, say main.c, and want to see how it differs from the file from which it was checked out, use

% prcs diff P1 main.c

By specifying versions, you can perform other comparisons. To compare the working version of main.c with that in version 0.1:

% prcs diff -r0.1 P1 main.c

To compare main.c in versions 0.1 and 0.3:

% prcs diff -r0.1 -r0.3 P1 main.c

To compare the working version of main.c with the latest in version 0:

% prcs diff -r0.@ P1 main.c

In place of `main.c', you may use any list of files and directories; each will be compared with files from the indicated versions. Mentioning a directory causes comparison of all files under that directory. Leaving off the file name list (e.g.,

% prcs diff P1
% prcs diff -r0.1 P1
% prcs diff -r0.@ P1

) performs the comparison for all files in the project versions.

The output of prcs diff indicates differences between files, and also cases where a file is present in one version (or working version) but not another.

If you have a working version that you have been modifying, you may have added files to it that are not yet reflected in the project descriptor (`.prj' file). Normally, prcs diff will ignore these files. To get a full comparison, you must first add these additional file names to the working project descriptor (see section Adding files to a project). If you don't really intend to add these files immediately, you can save and restore the original working project descriptor:

% cp P.prj tmp-P.prj
% prcs populate P
% prcs diff
 ... output from diff
% mv tmp-P.prj P.prj

or (if you haven't touched the project descriptor since checking it out), you can simply restore the project descriptor:

% prcs populate P
% prcs diff
 ... output from diff
% prcs checkout P P.prj

Merging into working files

After modifying the working files created by checking out the then-latest version of P1 (1.15, let us say), you may try to check them back in and discover that other minor versions of P1 version 1 have been added since 1.15 (prcs checkin will tell you this, and prcs diff or prcs merge -n will give details).

One way to deal with these differences is to merge the contents of your working files with the new version in the repository:

% prcs merge P1

By default, the checked-in version used by this command is the latest minor revision of the major revision of P1 indicated in your working `.prj' file (for this example, let's say version 1.17). The command prcs merge will prompt you for what action you want to take in cases where there are changes between the latest version and the version from which you checked out the working files.

The merge does not create and check in a new version; it merely updates your working files. It will also update your `P1.prj' file to indicate that it came from the version specified--implicitly or explicitly--by the merge subcommand, and you may perform a check-in as a new version.

Creating a new major version

Successive checkins will produce a sequence of minor versions of the same major version of a project. The major version name is useful for indicating such things as releases of a piece of software or "branches" of a project on which development will proceed independently. To create a new major version, specify it during check-in with the -r option. For example, to convert your working files into the first minor version of a new branch of project P1 called `MyBranch', use the command

% prcs checkin -rMyBranch P1

Modify at will; your modifications will be part of major version `MyBranch', and will be invisible to others using the repository unless they specifically ask for that major version. To merge back into the main branch (or any other), just use `prcs diff' and `prcs merge', as above:

% prcs merge -r0.@ P1

To copy an entire checked-in version into a new major version, use a sequence of commands like the following.

% prcs checkout -r0.@ P1 P1.prj
% prcs checkin -r1 P1 P1.prj

Only the project-version descriptor actually gets checked out and in. Because the file list for `P1.prj' remains unchanged, the two versions share all the same files (except for those files that contain certain keywords. See section 9 Keywords.)

Summary of really basic use

The simplest possible use of PRCS is just to use it to keep a single thread of project versions, thus allowing you to "roll back" at any time, and allowing multiple people to do maintenance on a single system simultaneously.

To start things off with a new project, P1, type

% prcs checkout P1

in the working directory where you are developing your project. (If you haven't yet established a repository, PRCS will create one.) If the project was already underway before you created a PRCS project for it, you will probably want to start off by bringing your existing files under version control. To do so, type

% prcs populate P1

Edit the file `P1.prj' to remove any files you don't want to control (like `.o' files, back-up files, and executables). You can also specify the list of files "in the population" on the command line. The files in any directories in this list will be included recursively. In effect, specifying no files is equivalent to specifying "." (the current directory).

% prcs populate P1 file1 file2

Whenever you want to checkpoint your project, type

% prcs checkin

from the root working directory (the one with `P1.prj' in it). If someone else has checked in files in the meantime, you will be notified of discrepancies, which you can handle by typing

% prcs merge

from the root working directory and (after it's done), editing the files.

Whenever it comes time to begin working on a deposited version of the project, you can go to a clean directory and check out the latest version with

% prcs checkout P1

Make your modifications and check back in as before.


Go to the first, previous, next, last section, table of contents.